Aller au contenu
Documentation

Limitations et migration vers 4.0

Ce que la version 4.0 ne peut pas intercepter et comment le contourner, suivi du guide de migration complet depuis 3.x.

Traduit de l’anglais. La page anglaise fait référence. Lire l’original

Cette page comporte deux parties. La première recense ce que la version 4.0 n’intercepte pas, pourquoi, et quoi faire à la place. La seconde est le guide de migration complet de 3.x vers 4.0, dans l’ordre où vous devez l’appliquer.

Les limitations sont présentées telles qu’elles sont. La plupart viennent de PHP lui-même, et chacune échoue de façon prévisible : soit le compilateur lève une WeavingException à la compilation, soit le membre est ignoré.

Méthodes et fonctions qui ne peuvent pas être interceptées

Section intitulée « Méthodes et fonctions qui ne peuvent pas être interceptées »

Une méthode ou une fonction déclarée function &name() ne peut pas être interceptée. Les call contexts (contextes d’appel) et les behaviors (comportements) retournent des valeurs : l’appelant obtiendrait donc une copie au lieu de la référence. Sa compilation échoue avec une WeavingException.

Excluez ces méthodes d’une matching rule (règle de correspondance) large avec !matchReturningByReference() :

#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]

En 3.x, le call context retournait une copie accompagnée d’une notice. En 4.0, c’est une erreur : vous repérez donc ces méthodes dès la compilation.

Une méthode qu’une classe importe d’un trait et qui porte #[\Override] ne peut pas être interceptée dans cette classe. PHP copie l’attribut sur l’alias privé qu’appelle le proxy, et cet alias ne redéfinit rien. Sa compilation échoue avec une WeavingException.

Vous avez quatre possibilités :

  • Exclure les méthodes de trait de la règle avec && !matchInherited().
  • Exclure uniquement cette méthode, par exemple && !execution(public Foo->hello(*)).
  • Retirer #[\Override] du trait.
  • Cibler le trait lui-même, par exemple execution(public HelloTrait->hello(*)). Le trait est compilé, ce qui fonctionne avec #[\Override], et le behavior s’applique dans toutes les classes qui utilisent le trait.

Les méthodes de trait qu’une classe hérite de sa classe parente ne sont pas concernées.

Pour une méthode qui contient yield, le behavior s’exécute à l’appel de la méthode, et proceed() retourne l’objet Generator. Le behavior ne voit pas les valeurs produites : elles sont générées plus tard, pendant que l’appelant itère.

getArguments() liste les arguments par position. Un paramètre variadique par référence (&...$values) est transmis par valeur à la méthode d’origine.

Le proxy conserve l’attribut. Les frames du framework qui transportent les arguments sous forme de tableau les masquent : le __invoke() du call context, le __initialization() généré et le new réécrit.

Deux fonctions internes situées entre le call context et la méthode d’origine ne peuvent pas les masquer :

  • ReflectionMethod::invokeArgs(), pour les méthodes d’instance et les constructeurs
  • forward_static_call_array(), pour les méthodes statiques

Leurs frames dans Throwable::getTrace() contiennent toujours le tableau d’arguments, que la forme texte de la trace affiche comme Array. Les outils de suivi d’erreurs qui collectent les arguments des frames le voient. Avec zend.exception_ignore_args=On, la valeur par défaut en production, aucune frame n’a d’arguments.

Les proxies des fonctions interceptées sont générés avec declare(strict_types=1), un fichier par espace de noms. Les arguments sont convertis selon le mode du fichier appelant avant l’entrée dans le proxy.

Les règles access(...) interceptent les lectures et écritures de propriétés d’instance grâce aux property hooks natifs de PHP 8.4 sur le proxy généré : les hooks générés font passer les lectures et les écritures par des call contexts ClassFieldAccess. Voir l’interception de propriétés pour ce que cela vous apporte. Les propriétés suivantes sont volontairement ignorées :

Propriété Pourquoi
Propriétés static PHP n’a pas de property hooks pour les propriétés statiques. C’est une contrainte du moteur.
Propriétés readonly, y compris public private(set) readonly PHP n’autorise pas de hooks sur les propriétés readonly.
Propriétés qui ont déjà des hooks get ou set Le framework ne peut pas composer ses hooks avec ceux que vous avez définis.
Propriétés final héritées de classes parentes Non pris en charge.
Propriétés private héritées Non pris en charge.

Les cibles prises en charge sont les propriétés déclarées dans la classe compilée elle-même, y compris les propriétés promues par le constructeur, ainsi que les propriétés public et protected héritées des classes parentes.

Une propriété ignorée ne lève pas d’erreur. Si votre règle la sélectionne, la propriété est simplement laissée de côté sans avertissement : AdviceMatcher écarte les propriétés statiques, readonly et dotées de hooks avant que le moindre code de proxy soit généré. Le générateur de propriétés refuse lui aussi une telle propriété avec une WeavingException, par sécurité.

La visibilité asymétrique des propriétés non readonly est préservée. public protected(set) string $name conserve ses modificateurs dans la classe proxy.

Le framework construit l’interception de propriétés sur les property hooks de PHP 8.4, et son conteneur utilise les objets paresseux (lazy objects) de PHP 8.4 pour les services différés. Deux aspects de ce fonctionnement ont des limites.

L’initialisation des objets paresseux ne peut pas être interceptée

Section intitulée « L’initialisation des objets paresseux ne peut pas être interceptée »

PHP 8.4 a introduit ReflectionClass::newLazyProxy() et ReflectionClass::newLazyGhost() pour l’initialisation paresseuse des objets. Le Container du framework utilise des proxies paresseux natifs pour ses propres services différés et pour les behavior classes (classes de comportement) enregistrées par nom de classe. Récupérer un tel service renvoie une instance newLazyProxy() typée et correcte vis-à-vis d’instanceof. La factory enregistrée ne s’exécute qu’à la première interaction réelle avec cet objet.

Les classes que PHP ne peut pas rendre paresseuses reviennent à une construction immédiate : les classes internes et leurs sous-classes autres que stdClass, les classes abstraites et les enums.

Il n’existe aucun call context pour le moment où un proxy paresseux matérialise son instance sous-jacente : l’initialisation des objets paresseux elle-même ne peut donc pas être interceptée.

Fonctionnalité PHP 8.4 Prise en charge Remarques
Property hooks sur de nouvelles propriétés Générés par le framework Utilisés pour l’interception access(...)
Propriétés avec des hooks existants Ignorées Le framework ne peut pas composer avec des hooks définis par l’utilisateur
Propriétés readonly Ignorées Les hooks ne sont pas autorisés sur les propriétés readonly
Visibilité asymétrique (non readonly) Préservée Les modificateurs de visibilité sont copiés dans le proxy
Attribut #[\Deprecated] Propagé Copié sur les méthodes et les classes du proxy
Objets paresseux (newLazyProxy) Non interceptables Aucun call context pour l’initialisation paresseuse

Les notes sur PHP 8.5 reposent sur un audit du framework sous PHP 8.5.10 et PHP 8.6.0beta2.

  • Opérateur pipe |>. Il fonctionne dans les corps de méthodes compilés. Les corps de méthodes sont déplacés tels quels dans le trait de corps <Class>OriginalTrait : toute syntaxe d’expression PHP 8.5 qu’ils contiennent est donc préservée.
  • clone with. Les expressions dans le code compilé fonctionnent comme prévu.
  • #[\NoDiscard]. L’attribut est copié sur la méthode du proxy généré, et le call context retourne la valeur de la méthode interceptée. L’avertissement du moteur « return value not used » continue de se déclencher pour les méthodes compilées.
  • Attributs sur les constantes de classe, y compris #[\Deprecated]. Les constantes de classe restent dans le trait généré avec leurs attributs.
  • Closures et first-class callables comme valeurs par défaut de paramètres. Ils survivent à la compilation dans les signatures des méthodes du proxy.
  • Visibilité asymétrique statique. Les propriétés static à visibilité asymétrique (public static private(set)) fonctionnent sur les classes compilées. Elles ne sont jamais ciblées par les règles access(...).
  • Résolution de self et parent par la réflexion. Sous PHP 8.5, ReflectionNamedType::getName() résout les types de retour self et parent en noms de classes concrets. Les générateurs de proxies lisent le nœud de type brut de l’AST quand il est disponible : les mots-clés self et parent sont ainsi préservés dans les proxies générés.

new dans les initialiseurs n’est pas intercepté

Section intitulée « new dans les initialiseurs n’est pas intercepté »

Une expression new dans une expression constante est évaluée par le moteur. Cela couvre la valeur par défaut d’un paramètre ou d’un paramètre promu du constructeur, l’initialiseur d’une variable statique et l’argument d’un attribut. Le compilateur laisse ces expressions telles quelles : le code fonctionne, mais un behavior initialization(...) ne s’exécute pas pour les objets qu’elles créent. Seules les expressions new du code exécutable sont interceptées.

Les propriétés statiques ne sont jamais interceptables

Section intitulée « Les propriétés statiques ne sont jamais interceptables »

Les propriétés statiques, y compris les propriétés static de PHP 8.5 à visibilité asymétrique, ne peuvent pas être interceptées avec des règles access(...). Les property hooks de PHP n’existent pas pour les propriétés statiques : le framework n’a donc aucun mécanisme d’interception pour elles, et AdviceMatcher les exclut de l’interception de propriétés. C’est une contrainte du moteur PHP, pas un bug.

Fonctionnalité PHP 8.5 Prise en charge Remarques
Opérateur pipe |> dans les corps de méthodes Fonctionne Les corps sont déplacés tels quels dans le trait généré
clone with Fonctionne
#[\NoDiscard] Propagé Copié dans le proxy ; le call context retourne la valeur
Attributs sur les constantes de classe (y compris #[\Deprecated]) Préservés Les constantes restent dans le trait généré
Closures et first-class callables comme valeurs par défaut de paramètres Fonctionne
Visibilité asymétrique statique (non interceptée) Préservée Les propriétés statiques ne sont jamais interceptables avec access()
Résolution de self/parent par la réflexion Gérée Les nœuds de type bruts de l’AST sont utilisés pour générer les proxies
new dans les initialiseurs Non intercepté Évalué par le moteur ; les behaviors initialization(...) ne s’exécutent pas pour lui
Interception de propriétés statiques avec access() Jamais Pas de property hooks pour les propriétés statiques (contrainte du moteur PHP)

Portée de la compilation et limites des matching rules

Section intitulée « Portée de la compilation et limites des matching rules »

Seules les classes chargées après l’initialisation du noyau (kernel) sont compilées. Une classe chargée avant ce moment s’exécute sans ses behaviors. Initialisez le noyau le plus tôt possible dans votre contrôleur frontal. Les bridges de frameworks doivent démarrer en premier ; voir Intégrations pour la façon dont chaque bridge s’en charge.

La liste d’arguments d’une matching rule est toujours (*). Une règle sélectionne les méthodes par classe, nom, modificateurs, type de retour et attributs, jamais par valeurs d’arguments ni par types de paramètres. Pour agir sur des arguments précis, sélectionnez la méthode et inspectez $invocation->getArguments() dans le behavior. La syntaxe complète se trouve dans Behaviors et matching rules.

Ces chiffres proviennent du benchmark du framework lui-même, dans docs/performance.md : une petite application de boutique d’environ 250 fichiers, 94 classes compilées et 6 behavior classes, sous PHP 8.5.12 avec le JIT désactivé. Ce fichier explique comment ils ont été mesurés et comment les reproduire.

Tant qu’une règle initialization est enregistrée, chaque new des fichiers générés passe par le transformateur. Une classe sans behavior d’initialisation (et dotée d’un constructeur public) est toujours créée par un new natif, qui coûte environ 130 ns de plus qu’un simple new. Une classe avec des behaviors d’initialisation passe par le call context complet. Préférez les règles de méthode lorsqu’elles suffisent.

Avec 'debug' => true, les classes générées sont servies via le stream filter : les points d’arrêt Xdebug et les constantes magiques pointent vers vos fichiers d’origine, et les fichiers modifiés sont recompilés automatiquement. Dans le benchmark, les requêtes à chaud en mode debug prennent plus de deux fois plus de temps qu’en mode production. Utilisez 'debug' => false en production ; voir Production et performances.

La version 4.0 remplace le compilateur fondé sur l’héritage par un compilateur fondé sur les traits, génère les behaviors sous forme de first-class callables et reconstruit les caches pour PHP 8.4. La plupart des applications n’ont besoin que de la liste de contrôle ci-dessous. Les sections suivantes décrivent chaque changement incompatible. Les noms d’API qu’elles citent gardent les termes classiques ; le tableau des termes les fait correspondre aux mots employés ici. La liste complète des changements se trouve dans le CHANGELOG.

  1. Passez à PHP 8.4 ou plus récent et mettez à jour les dépendances (voir Prérequis et dépendances ci-dessous).

  2. Rendez public chaque méthode de behavior de vos behavior classes (voir Behavior classes ci-dessous).

  3. Enregistrez les behavior classes avec add() ou addLazyService() au lieu de registerAspect().

  4. Remplacez les jokers ? des matching rules par *, et réécrivez les règles dynamic(...).

  5. Supprimez le répertoire de cache, puis préchauffez-le à nouveau. L’argument est le fichier qui initialise votre noyau :

    Fenêtre de terminal
    vendor/bin/aspect cache:warmup:aop public/index.php
  6. Si vous utilisez le bridge Doctrine, basculez la découverte des entités sur WovenEntityClassLocator.

  • PHP 8.4+ avec ext-tokenizer.
  • Mettez à jour les dépendances avec Composer. Les versions requises sont listées dans composer.json.
  • psr/container est une nouvelle dépendance, et nikic/php-parser est installé via goaop/parser-reflection.
  • laminas/laminas-code n’est plus utilisé. Les proxies sont générés par le paquet interne Go\Proxy\Generator. Le code qui étendait les générateurs du framework, ou qui comptait sur les classes de générateurs laminas fournies avec le framework, doit être mis à jour.
  • bin/aspect nécessite symfony/console.

Tous les formats de cache ont changé, et aucun fichier de cache 3.x n’est réutilisé.

  • Organisation des proxies. Le sous-répertoire _proxies disparaît. Un proxy est stocké sous le répertoire de cache, au chemin relatif de son fichier source, et la source générée (le corps d’origine de la classe sous forme de trait <Class>OriginalTrait) juste à côté.
  • Class map. _include.cache associe chaque classe compilée à son fichier en cache et est transmis à Composer au démarrage. Il associe aussi chaque fichier source connu à son fichier en cache (ou à null s’il n’est pas transformé) pour les includes interceptés par INTERCEPT_INCLUDES. Un répertoire de cache qui en est dépourvu est considéré comme périmé.
  • Cache des behavior classes. Les blobs sérialisés {cacheDir}/_aspect/sha1(FQCN) sont remplacés par des fichiers PHP ordinaires placés à côté des sources générées : {appDir}/src/Aspect/LoggingAspect.php est mis en cache sous {cacheDir}/src/Aspect/LoggingAspect.cache.php. Les intercepteurs ne sont plus sérialisables : AbstractInterceptor::__serialize(), __unserialize(), serializeAdvice() et unserializeAdvice() sont supprimés.

Les fichiers de métadonnées portent une version de format. Avec Features::PREBUILT_CACHE, un cache construit par une autre version du framework est rejeté avec une exception au lieu d’être reconstruit à l’exécution.

Features::PREBUILT_CACHE fait désormais entièrement confiance au cache. Les sondes du répertoire et de ses droits d’écriture, les comparaisons de filemtime, les vérifications des ressources surveillées et les contrôles de fraîcheur des caches des behavior classes sont tous supprimés. Reconstruire le cache au déploiement relève de la responsabilité de celui qui déploie.

L’option cacheFileMode est validée. Ce doit être un entier compris entre 0600 et 0777 qui accorde au propriétaire les droits de lecture et d’écriture. Les répertoires reçoivent des droits de parcours correspondant aux bits de lecture du mode.

Les proxies générés appellent les behaviors comme des first-class callables sur l’instance de la behavior class. Une méthode portant #[Before], #[After], #[Around] ou #[AfterThrowing] doit donc être public. Le loader lève une AspectException pour les méthodes de behavior protected ou private. Les méthodes qui ne portent que #[Pointcut] peuvent garder n’importe quelle visibilité.

3.x
#[Before('execution(public Example->*(*))')]
protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0
#[Before('execution(public Example->*(*))')]
public function beforeMethod(MethodInvocation $invocation): void {}

Une méthode de behavior class porte au plus un attribut parmi #[Before], #[After], #[Around] et #[AfterThrowing]. Un second attribut lève une AspectException. Scindez une telle méthode en une méthode par behavior. #[Pointcut] peut toujours être combiné avec un attribut de behavior sur la même méthode, et les attributs qui n’appartiennent pas au framework sont ignorés.

AspectContainer::registerAspect() est supprimé. Les behavior classes sont des services de conteneur ordinaires.

Avant, en 3.x :

app/ApplicationAspectKernel.php
// 3.x
protected function configureAop(AspectContainer $container)
{
$container->registerAspect(new MonitorAspect());
}

Après, en 4.0 :

app/ApplicationAspectKernel.php
// 4.0
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed when one of its behaviors runs for the first time
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative
// $container->add(MonitorAspect::class, new MonitorAspect());
}

addLazyService() stocke une factory et construit le service lors de sa première récupération. Le code qui s’attendait à ce qu’une instance de proxy paresseux existe dès le démarrage doit appeler getService(). Une factory qui retourne un objet du mauvais type échoue désormais à la première utilisation, et non à l’enregistrement.

AspectContainer::addResource() fait partie de l’interface. onRegistration() vous permet de réagir aux enregistrements différés de services qui implémentent une interface.

AspectContainer étend Psr\Container\ContainerInterface : vous pouvez donc passer le conteneur à tout code qui attend un conteneur PSR-11.

  • AspectContainer::getValue() est renommé en get().
  • has() vient de l’interface PSR, avec la même signature.
  • Une containerClass personnalisée implémente get() au lieu de getValue(), ainsi que setDelegate(), qui rattache le conteneur de votre application. Voir Configuration et CLI.
4.0
// before
$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');

Un identifiant inconnu lève ServiceNotFoundException, qui implémente Psr\Container\NotFoundExceptionInterface. getService() lève Go\Aop\Exception\ContainerException lorsque l’entrée n’est pas une instance de la classe demandée. Cette exception est une InvalidConfigurationException qui implémente Psr\Container\ContainerExceptionInterface.

Le renommage ne concerne que le conteneur. FieldAccess::getValue() sur les call contexts de propriété est inchangé.

  • Les interfaces marqueurs AdviceBefore, AdviceAfter et AdviceAround sont supprimées. Advice exige getType(): AdviceTypeEnum, avec les cas Before, After, AfterThrowing, Around et Introduction.
  • Les constructeurs d’invocation (DynamicTraitAliasMethodInvocation, StaticTraitAliasMethodInvocation, ReflectionFunctionInvocation) exigent un Closure $closureToCall non nullable.
  • DeclareError est supprimé : l’attribut, DeclareErrorInterceptor et PointcutBuilder::declareError(). Émettez plutôt des avertissements ou levez des exceptions depuis un behavior #[Before] ou #[Around].

Les méthodes qui retournent par référence sont refusées

Section intitulée « Les méthodes qui retournent par référence sont refusées »

La compilation d’une méthode ou d’une fonction déclarée function &name() échoue avec une WeavingException, car le call context retournerait une copie au lieu de la référence. La 3.x retournait une copie accompagnée d’une notice. Ajoutez && !matchReturningByReference() aux règles qui sélectionnent de telles méthodes.

Dans les motifs de noms et de types, ? n’est plus un joker d’un seul caractère, car il entrait en conflit avec les types nullables. Dans les motifs de type de retour, un ? initial marque le type nullable : ?Foo équivaut à Foo|null. Remplacez les jokers ? par *.

La règle dynamic(...) est supprimée, de même que MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC et les paramètres $instanceOrScope et $arguments de Pointcut::matches(). Interceptez la méthode magique elle-même et lisez le nom invoqué dans les arguments.

Avant, en 3.x :

3.x
#[Around('dynamic(public Foo->save*(*))')]

Après, en 4.0 :

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • Précédence des modificateurs. Les modificateurs séparés par des espaces doivent tous être présents, et | est plus prioritaire. final public|protected signifie final ET (public OU protected). En 3.x, cette règle sélectionnait aussi toutes les méthodes publiques non finales.
  • Foo+ inclut Foo. Ce motif sélectionne désormais aussi la classe ou l’interface Foo elle-même, ainsi que les classes qui utilisent le trait Foo. Ajoutez && !within(Foo) pour exclure le type lui-même.
  • Les règles d’attributs sélectionnent les sous-classes. @execution(Attr) et les autres règles d’attributs sélectionnent aussi les attributs qui étendent Attr.
  • * correspond aussi à rien. Dans les motifs de noms et de types de retour, * représente n’importe quels caractères d’une partie de nom, y compris aucun. En 3.x, il fallait au moins un caractère : Sensor* ignorait la classe Sensor elle-même, et set* ignorait une méthode nommée set(). Ces règles les sélectionnent désormais aussi. Excluez-les si besoin avec && !execution(public Foo->set(*)) ou && !within(Foo).
  • Les alternatives | restent dans leur partie de nom. Ns\A|B sélectionne Ns\A et Ns\B. En 3.x, cela signifiait Ns\A ou la classe globale B. Un motif qui listait des classes d’espaces de noms différents (Foo\A|Bar\B) doit être écrit sous forme de deux règles : execution(public Foo\A->*(*)) || execution(public Bar\B->*(*)).
  • ModifierPointcut est final et immuable. Les masques sont des arguments du constructeur, et andMatch(), orMatch() et notMatch() retournent une nouvelle instance.

Le corps d’origine de la classe est converti en trait, <Class>OriginalTrait. La classe proxy conserve le nom, le parent et les interfaces d’origine, et utilise ce trait avec des alias privés <method>OriginalAlias. En 3.x, le proxy étendait une classe parente renommée <Class>__AopProxied. Cela concerne le code qui s’appuyait sur cette couche d’héritage :

  • Le proxy n’a plus de classe parente renommée. get_parent_class(), parent:: dans la classe et les vérifications instanceof voient le parent d’origine.
  • AspectContainer::AOP_PROXIED_SUFFIX est supprimé. Utilisez ORIGINAL_TRAIT_SUFFIX ('OriginalTrait') ou ORIGINAL_TRAIT_FILE_SUFFIX ('OriginalTrait.php').
  • AbstractMethodInvocation::TRAIT_ALIAS_PREFIX est remplacé par TRAIT_ALIAS_SUFFIX ('OriginalAlias').
  • Les hooks de InitializationAware et StaticInitializationAware s’appellent __initialization() et __staticInitialization().
  • self:: dans le code généré se résout en la classe proxy : SelfValueTransformer et SelfValueVisitor sont donc supprimés.
  • Go\Aop\Features est une classe finale au lieu d’une interface. Les constantes sont inchangées, mais elle ne peut plus être implémentée. Features::ALL combine tous les drapeaux, et AspectKernel::hasFeature() lève une exception pour un drapeau inconnu.
  • Features::PARAMETER_WIDENING est supprimé. Retirez ce drapeau des options de votre noyau si vous le passiez.

Ces classes, méthodes et constantes publiques n’avaient aucun usage dans le framework et sont supprimées :

  • L’attribut #[Aspect] (Go\Lang\Attribute\Aspect). Le framework ne l’a jamais lu : les behavior classes sont identifiées par l’implémentation de Go\Aop\Aspect. Retirez l’attribut de vos behavior classes.
  • Pointcut::KIND_TRAIT. Pointcut::KIND_ALL vaut 119 au lieu de 127.
  • Go\Proxy\Part\InterceptedConstructorGenerator et Go\Proxy\Part\FunctionParameterList.
  • InterceptedMethodGenerator::getBody() et setBody(), CachePathManager::setCacheDir(), ainsi que AopComposerLoader::wasInitialized(). AopComposerLoader::init() retourne le même drapeau.
  • L’entrée de conteneur 'kernel.options'. Utilisez AspectKernel::getOptions().
3.x / début du développement de 4.0 4.0
TransformerResultEnum::RESULT_TRANSFORMED TransformerResult::Transformed
TransformerResultEnum::RESULT_ABSTAIN TransformerResult::Abstain
TransformerResultEnum::RESULT_ABORTED TransformerResult::Aborted
FieldAccessType::READ / WRITE FieldAccessType::Read / Write
AspectContainer::AOP_PROXIED_SUFFIX AspectContainer::ORIGINAL_TRAIT_SUFFIX
AspectContainer::getValue() AspectContainer::get() (PSR-11)

Les enums de Go\Proxy\Generator (Visibility, PropertyModifier, ClassModifier) utilisent eux aussi des cas en PascalCase. Les transformateurs de source personnalisés retournent des cas de TransformerResult, et les behaviors qui comparent getAccessType() utilisent les nouveaux noms de cas :

if ($access->getAccessType() === FieldAccessType::WRITE) {
if ($access->getAccessType() === FieldAccessType::Write) {
  • AspectKernel::registerTransformers(), qui retournait des instances de transformateurs, est remplacé par registerTransformerServices(AspectContainer $container), qui enregistre des services de conteneur différés. Redéfinissez-la pour remplacer, omettre, réordonner ou étendre les transformateurs intégrés. Pour en ajouter un à la fin, appelez $container->addLazyService(MyTransformer::class, ...) depuis configureAop().
  • CachingTransformer est supprimé : la décision de cache se trouve dans SourceTransformingLoader. SourceTransformingLoader::addTransformer() est supprimé, et transformCode() retourne le TransformerResult global.
  • StreamMetaData::$source est en lecture seule : il est reconstruit à partir de $tokenStream à chaque lecture. Les transformateurs personnalisés modifient les tokens de $tokenStream, ou les remplacent avec setTokenStreamFromRawTokens().
  • ConstructorExecutionTransformer, FilterInjectorTransformer et MagicConstantTransformer ne sont plus des SourceTransformer. Ce sont des règles NodeRewriter, appliquées par un seul parcours SyntaxTreeRewriter de l’arbre syntaxique. Ce parcours est un service du framework : il ouvre la chaîne avant WeavingTransformer, même lorsque registerTransformerServices() est redéfinie.
  • Les SourceTransformer personnalisés s’enregistrent comme avant. Pour réécrire des nœuds isolés, enregistrez un service NodeRewriter plutôt qu’un transformateur qui parcourt lui-même l’arbre. Voir Configuration et CLI pour étendre le pipeline de transformation.

Les classes qui n’ont jamais été pensées pour être étendues sont désormais final :

  • Go\Core\Container, Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\Instrument\ClassLoading\AopComposerLoader, SourceTransformingLoader, Go\Instrument\PathResolver
  • les transformateurs WeavingTransformer, FilterInjectorTransformer, MagicConstantTransformer et StreamMetaData
  • les générateurs de proxies EnumProxyGenerator, TraitProxyGenerator et FunctionProxyGenerator
  • les attributs #[Before], #[After], #[Around], #[AfterThrowing], #[Pointcut] et #[DeclareParents]

Go\Lang\Attribute\AbstractInterceptor est abstract. Les classes qui ne font que partie de la machinerie du framework sont marquées @internal et ne sont couvertes par aucune promesse de rétrocompatibilité : AdviceMatcher, AspectLoader, CachedAspectLoader, CachePathManager, CacheWarmer, Enumerator, InterceptorInjector, The et NativeLazyProxy.

Remplacez les sous-classes de ces classes par de la composition, ou par votre propre conteneur ou transformateur enregistré dans configureAop() ou registerTransformerServices().

Chaque exception levée par le framework implémente Go\Aop\Exception\ExceptionInterface : un seul catch intercepte donc n’importe lequel de ses échecs. Plusieurs points de levée ont changé de type :

Situation 3.x 4.0
Options de noyau, enregistrements dans le conteneur ou saisie console invalides RuntimeException, InvalidArgumentException, UnexpectedValueException InvalidConfigurationException (une InvalidArgumentException)
Matching rule invalide UnexpectedValueException, InvalidArgumentException PointcutSyntaxException (une AspectException)
Identifiant de conteneur inconnu OutOfBoundsException ServiceNotFoundException (une OutOfBoundsException et une NotFoundExceptionInterface PSR-11)
Entrée de conteneur du mauvais type dans getService() InvalidArgumentException ContainerException (une InvalidConfigurationException et une ContainerExceptionInterface PSR-11)
Compilation, génération de proxies, écritures du cache RuntimeException, LogicException, InvalidArgumentException WeavingException (une RuntimeException)
Behavior qui ne peut pas être mis en cache Go\Core\Cache\NotCompilableException Go\Aop\Exception\NotCompilableException
Behavior class invalide, erreurs d’exécution du call context Go\Aop\AspectException Go\Aop\Exception\AspectException, Go\Aop\Exception\InvocationException

Là où vous interceptiez les types SPL listés ci-dessus, interceptez ExceptionInterface ou les nouveaux types.

Le bridge ne réécrit plus les métadonnées des entités. Le contournement par mapped superclass de la 3.x ne concernait que le moteur fondé sur l’héritage, et Doctrine mappe correctement une entité compilée telle quelle. Configurez plutôt deux choses (Doctrine ORM 3.6+) :

use Doctrine\ORM\Events;
use Doctrine\ORM\Mapping\Driver\AttributeDriver;
use Go\Bridge\Doctrine\MetadataLoadInterceptor;
use Go\Bridge\Doctrine\WovenEntityClassLocator;
// Discover entities through the autoloader, which serves the generated classes
$configuration->setMetadataDriverImpl(
new AttributeDriver(WovenEntityClassLocator::createFromDirectories([__DIR__ . '/src/Entity'])),
);
// Intercepted properties become hooked properties, which Doctrine supports with native lazy objects
$configuration->enableNativeLazyObjects(true);
// Optional: reports misconfiguration early; a plain listener, no longer an EventSubscriber
$eventManager->addEventListener(Events::loadClassMetadata, new MetadataLoadInterceptor());

Les commandes déclarent leur nom avec #[AsCommand] et sont chargées en différé par bin/aspect. Chaque commande retourne Command::SUCCESS ou Command::FAILURE.

  • En 3.x, debug:weaving retournait le nombre brut d’erreurs. Si un script s’appuyait sur ce nombre, vérifiez plutôt le code de sortie.
  • cache:warmup:aop échoue lorsqu’un fichier ne peut pas être compilé : un script de déploiement qui ignorait les erreurs de préchauffage s’arrête désormais là. Ajoutez --fail-fast pour vous arrêter à la première erreur :
Fenêtre de terminal
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast

© 2026 Alexander Lisachenko