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 »Méthodes qui retournent par référence
Section intitulée « Méthodes qui retournent par référence »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.
Méthodes de trait avec #[\Override]
Section intitulée « Méthodes de trait avec #[\Override] »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.
Générateurs
Section intitulée « Générateurs »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.
Paramètres variadiques par référence
Section intitulée « Paramètres variadiques par référence »getArguments() liste les arguments par position. Un paramètre variadique par référence (&...$values) est transmis par valeur à la méthode d’origine.
#[\SensitiveParameter] dans les traces d’appels
Section intitulée « #[\SensitiveParameter] dans les traces d’appels »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 constructeursforward_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.
strict_types des proxies de fonctions
Section intitulée « strict_types des proxies de fonctions »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.
Interception de propriétés
Section intitulée « Interception de propriétés »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.
Notes sur PHP 8.4
Section intitulée « Notes sur PHP 8.4 »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.
Récapitulatif PHP 8.4
Section intitulée « Récapitulatif PHP 8.4 »| 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 |
Notes sur PHP 8.5
Section intitulée « Notes sur PHP 8.5 »Les notes sur PHP 8.5 reposent sur un audit du framework sous PHP 8.5.10 et PHP 8.6.0beta2.
Ce qui fonctionne sous PHP 8.5
Section intitulée « Ce qui fonctionne sous PHP 8.5 »- 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èglesaccess(...). - Résolution de
selfetparentpar la réflexion. Sous PHP 8.5,ReflectionNamedType::getName()résout les types de retourselfetparenten 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ésselfetparentsont 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.
Récapitulatif PHP 8.5
Section intitulée « Récapitulatif PHP 8.5 »| 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 »Classes chargées avant le démarrage du noyau
Section intitulée « Classes chargées avant le démarrage du noyau »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.
Les arguments ne peuvent pas être sélectionnés
Section intitulée « Les arguments ne peuvent pas être sélectionnés »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.
Coûts d’exécution à connaître
Section intitulée « Coûts d’exécution à connaître »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.
Les règles initialization() touchent chaque new
Section intitulée « Les règles initialization() touchent chaque new »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.
Le mode debug est fait pour le développement
Section intitulée « Le mode debug est fait pour le développement »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.
Migrer de 3.x vers 4.0
Section intitulée « Migrer de 3.x vers 4.0 »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.
Liste de contrôle rapide
Section intitulée « Liste de contrôle rapide »-
Passez à PHP 8.4 ou plus récent et mettez à jour les dépendances (voir Prérequis et dépendances ci-dessous).
-
Rendez
publicchaque méthode de behavior de vos behavior classes (voir Behavior classes ci-dessous). -
Enregistrez les behavior classes avec
add()ouaddLazyService()au lieu deregisterAspect(). -
Remplacez les jokers
?des matching rules par*, et réécrivez les règlesdynamic(...). -
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 -
Si vous utilisez le bridge Doctrine, basculez la découverte des entités sur
WovenEntityClassLocator.
Prérequis et dépendances
Section intitulée « Prérequis et dépendances »- PHP 8.4+ avec
ext-tokenizer. - Mettez à jour les dépendances avec Composer. Les versions requises sont listées dans
composer.json. psr/containerest une nouvelle dépendance, etnikic/php-parserest installé viagoaop/parser-reflection.laminas/laminas-coden’est plus utilisé. Les proxies sont générés par le paquet interneGo\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/aspectnécessitesymfony/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
_proxiesdisparaî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.cacheassocie 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 ànulls’il n’est pas transformé) pour les includes interceptés parINTERCEPT_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.phpest mis en cache sous{cacheDir}/src/Aspect/LoggingAspect.cache.php. Les intercepteurs ne sont plus sérialisables :AbstractInterceptor::__serialize(),__unserialize(),serializeAdvice()etunserializeAdvice()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.
Behavior classes
Section intitulée « Behavior classes »Les méthodes de behavior doivent être publiques
Section intitulée « Les méthodes de behavior doivent être publiques »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é.
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}Un seul attribut de behavior par méthode
Section intitulée « Un seul attribut de behavior par méthode »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.
Enregistrer les behavior classes
Section intitulée « Enregistrer les behavior classes »AspectContainer::registerAspect() est supprimé. Les behavior classes sont des services de conteneur ordinaires.
Avant, en 3.x :
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}Après, en 4.0 :
// 4.0protected 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.
Conteneur PSR-11
Section intitulée « Conteneur PSR-11 »AspectContainer étend Psr\Container\ContainerInterface : vous pouvez donc passer le conteneur à tout code qui attend un conteneur PSR-11.
AspectContainer::getValue()est renommé enget().has()vient de l’interface PSR, avec la même signature.- Une
containerClasspersonnalisée implémenteget()au lieu degetValue(), ainsi quesetDelegate(), qui rattache le conteneur de votre application. Voir Configuration et CLI.
// 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é.
API Advice et des intercepteurs
Section intitulée « API Advice et des intercepteurs »- Les interfaces marqueurs
AdviceBefore,AdviceAfteretAdviceAroundsont supprimées.AdviceexigegetType(): AdviceTypeEnum, avec les casBefore,After,AfterThrowing,AroundetIntroduction. - Les constructeurs d’invocation (
DynamicTraitAliasMethodInvocation,StaticTraitAliasMethodInvocation,ReflectionFunctionInvocation) exigent unClosure $closureToCallnon nullable. DeclareErrorest supprimé : l’attribut,DeclareErrorInterceptoretPointcutBuilder::declareError(). Émettez plutôt des avertissements ou levez des exceptions depuis un behavior#[Before]ou#[Around].
Matching rules
Section intitulée « Matching rules »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.
Le joker ? est supprimé
Section intitulée « Le joker ? est supprimé »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 *.
dynamic(...) est supprimé
Section intitulée « dynamic(...) est supprimé »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 :
#[Around('dynamic(public Foo->save*(*))')]Après, en 4.0 :
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}Matching rules qui ont changé
Section intitulée « Matching rules qui ont changé »- Précédence des modificateurs. Les modificateurs séparés par des espaces doivent tous être présents, et
|est plus prioritaire.final public|protectedsignifie final ET (public OU protected). En 3.x, cette règle sélectionnait aussi toutes les méthodes publiques non finales. Foo+inclutFoo. Ce motif sélectionne désormais aussi la classe ou l’interfaceFooelle-même, ainsi que les classes qui utilisent le traitFoo. 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 étendentAttr. *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 classeSensorelle-même, etset*ignorait une méthode nomméeset(). 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|BsélectionneNs\AetNs\B. En 3.x, cela signifiaitNs\Aou la classe globaleB. 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->*(*)). ModifierPointcutest final et immuable. Les masques sont des arguments du constructeur, etandMatch(),orMatch()etnotMatch()retournent une nouvelle instance.
Compilateur et code généré
Section intitulée « Compilateur et code généré »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érificationsinstanceofvoient le parent d’origine. AspectContainer::AOP_PROXIED_SUFFIXest supprimé. UtilisezORIGINAL_TRAIT_SUFFIX('OriginalTrait') ouORIGINAL_TRAIT_FILE_SUFFIX('OriginalTrait.php').AbstractMethodInvocation::TRAIT_ALIAS_PREFIXest remplacé parTRAIT_ALIAS_SUFFIX('OriginalAlias').- Les hooks de
InitializationAwareetStaticInitializationAwares’appellent__initialization()et__staticInitialization(). self::dans le code généré se résout en la classe proxy :SelfValueTransformeretSelfValueVisitorsont donc supprimés.Go\Aop\Featuresest une classe finale au lieu d’une interface. Les constantes sont inchangées, mais elle ne peut plus être implémentée.Features::ALLcombine tous les drapeaux, etAspectKernel::hasFeature()lève une exception pour un drapeau inconnu.Features::PARAMETER_WIDENINGest supprimé. Retirez ce drapeau des options de votre noyau si vous le passiez.
API inutilisée supprimée
Section intitulée « API inutilisée supprimée »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 deGo\Aop\Aspect. Retirez l’attribut de vos behavior classes. Pointcut::KIND_TRAIT.Pointcut::KIND_ALLvaut119au lieu de127.Go\Proxy\Part\InterceptedConstructorGeneratoretGo\Proxy\Part\FunctionParameterList.InterceptedMethodGenerator::getBody()etsetBody(),CachePathManager::setCacheDir(), ainsi queAopComposerLoader::wasInitialized().AopComposerLoader::init()retourne le même drapeau.- L’entrée de conteneur
'kernel.options'. UtilisezAspectKernel::getOptions().
Enums et constantes renommés
Section intitulée « Enums et constantes renommés »| 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) {Noyau et transformateurs
Section intitulée « Noyau et transformateurs »AspectKernel::registerTransformers(), qui retournait des instances de transformateurs, est remplacé parregisterTransformerServices(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, ...)depuisconfigureAop().CachingTransformerest supprimé : la décision de cache se trouve dansSourceTransformingLoader.SourceTransformingLoader::addTransformer()est supprimé, ettransformCode()retourne leTransformerResultglobal.StreamMetaData::$sourceest en lecture seule : il est reconstruit à partir de$tokenStreamà chaque lecture. Les transformateurs personnalisés modifient les tokens de$tokenStream, ou les remplacent avecsetTokenStreamFromRawTokens().ConstructorExecutionTransformer,FilterInjectorTransformeretMagicConstantTransformerne sont plus desSourceTransformer. Ce sont des règlesNodeRewriter, appliquées par un seul parcoursSyntaxTreeRewriterde l’arbre syntaxique. Ce parcours est un service du framework : il ouvre la chaîne avantWeavingTransformer, même lorsqueregisterTransformerServices()est redéfinie.- Les
SourceTransformerpersonnalisés s’enregistrent comme avant. Pour réécrire des nœuds isolés, enregistrez un serviceNodeRewriterplutôt qu’un transformateur qui parcourt lui-même l’arbre. Voir Configuration et CLI pour étendre le pipeline de transformation.
Classes finales et internes
Section intitulée « Classes finales et internes »Les classes qui n’ont jamais été pensées pour être étendues sont désormais final :
Go\Core\Container,Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\Instrument\ClassLoading\AopComposerLoader,SourceTransformingLoader,Go\Instrument\PathResolver- les transformateurs
WeavingTransformer,FilterInjectorTransformer,MagicConstantTransformeretStreamMetaData - les générateurs de proxies
EnumProxyGenerator,TraitProxyGeneratoretFunctionProxyGenerator - 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().
Exceptions
Section intitulée « Exceptions »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.
Bridge Doctrine
Section intitulée « Bridge Doctrine »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:weavingretournait 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-fastpour vous arrêter à la première erreur :
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast© 2026 Alexander Lisachenko
