Einschränkungen & Upgrade auf 4.0
Was Version 4.0 nicht abfangen kann und wie Sie das umgehen, gefolgt vom vollständigen Migrationsleitfaden von 3.x.
Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen
Diese Seite hat zwei Hälften. Die erste führt auf, was Version 4.0 nicht abfängt, warum, und was Sie stattdessen tun. Die zweite ist der vollständige Migrationsleitfaden von 3.x auf 4.0, in der Reihenfolge, in der Sie ihn anwenden sollten.
Die Einschränkungen stehen hier so, wie sie sind. Die meisten kommen von PHP selbst, und jede schlägt auf vorhersehbare Weise fehl: Entweder wirft der Compiler beim Kompilieren eine WeavingException, oder der Member wird übersprungen.
Methoden und Funktionen, die sich nicht abfangen lassen
Abschnitt betitelt „Methoden und Funktionen, die sich nicht abfangen lassen“Methoden mit Rückgabe per Referenz
Abschnitt betitelt „Methoden mit Rückgabe per Referenz“Eine als function &name() deklarierte Methode oder Funktion lässt sich nicht abfangen. Call-Contexts (Aufrufkontexte) und Behaviors (Verhalten) geben Werte zurück, der Aufrufer bekäme also eine Kopie statt der Referenz. Das Kompilieren einer solchen Methode schlägt mit einer WeavingException fehl.
Schließen Sie solche Methoden mit !matchReturningByReference() aus einer breiten Matching-Rule (Auswahlregel) aus:
#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]In 3.x gab der Call-Context eine Kopie mit einem Notice zurück. In 4.0 ist es ein Fehler, Sie finden diese Methoden also beim Kompilieren.
Trait-Methoden mit #[\Override]
Abschnitt betitelt „Trait-Methoden mit #[\Override]“Eine Methode, die eine Klasse aus einem Trait importiert und die #[\Override] trägt, lässt sich in dieser Klasse nicht abfangen. PHP kopiert das Attribut auf den privaten Alias, den der Proxy aufruft, und dieser Alias überschreibt nichts. Das Kompilieren einer solchen Methode schlägt mit einer WeavingException fehl.
Sie haben vier Möglichkeiten:
- Trait-Methoden mit
&& !matchInherited()aus der Regel ausschließen. - Nur diese Methode ausschließen, zum Beispiel
&& !execution(public Foo->hello(*)). #[\Override]aus dem Trait entfernen.- Den Trait selbst anvisieren, zum Beispiel
execution(public HelloTrait->hello(*)). Dann wird der Trait kompiliert, was mit#[\Override]funktioniert, und das Behavior greift in jeder Klasse, die den Trait verwendet.
Trait-Methoden, die eine Klasse von ihrer Elternklasse erbt, sind nicht betroffen.
Generatoren
Abschnitt betitelt „Generatoren“Bei einer Methode, die yield enthält, läuft das Behavior beim Aufruf der Methode, und proceed() gibt das Generator-Objekt zurück. Das Behavior sieht die per yield gelieferten Werte nicht: Sie entstehen erst später, während der Aufrufer iteriert.
Variadische Parameter per Referenz
Abschnitt betitelt „Variadische Parameter per Referenz“getArguments() listet die Argumente nach Position. Ein variadischer Parameter per Referenz (&...$values) wird an die ursprüngliche Methode per Wert übergeben.
#[\SensitiveParameter] in Stacktraces
Abschnitt betitelt „#[\SensitiveParameter] in Stacktraces“Der Proxy behält das Attribut. Die Frames des Frameworks, die die Argumente als Array tragen, verbergen sie: das __invoke() des Call-Contexts, das generierte __initialization() und das umgeschriebene new.
Zwei interne Funktionen zwischen dem Call-Context und der ursprünglichen Methode können sie nicht verbergen:
ReflectionMethod::invokeArgs(), für Instanzmethoden und Konstruktorenforward_static_call_array(), für statische Methoden
Ihre Frames in Throwable::getTrace() enthalten weiterhin das Argument-Array, das die Textform des Trace als Array ausgibt. Error-Tracker, die Frame-Argumente sammeln, sehen es. Mit zend.exception_ignore_args=On, dem Standard in Produktion, hat kein Frame Argumente.
strict_types von Funktions-Proxys
Abschnitt betitelt „strict_types von Funktions-Proxys“Die Proxys abgefangener Funktionen werden mit declare(strict_types=1) generiert, eine Datei pro Namespace. Die Argumente werden nach dem Modus der aufrufenden Datei umgewandelt, bevor der Proxy betreten wird.
Property-Interception
Abschnitt betitelt „Property-Interception“access(...)-Regeln fangen Lese- und Schreibzugriffe auf Instanz-Properties über native PHP-8.4-Property-Hooks auf dem generierten Proxy ab: Die generierten Hooks leiten Lese- und Schreibzugriffe durch ClassFieldAccess-Call-Contexts. Was Ihnen das bringt, zeigt Property-Interception. Die folgenden Properties werden bewusst übersprungen:
| Property | Warum |
|---|---|
static-Properties |
PHP hat keine Property-Hooks für statische Properties. Das ist eine Beschränkung der Engine. |
readonly-Properties, einschließlich public private(set) readonly |
PHP erlaubt keine Hooks auf Readonly-Properties. |
Properties, die bereits get- oder set-Hooks haben |
Das Framework kann seine Hooks nicht mit Hooks kombinieren, die Sie definiert haben. |
Von Elternklassen geerbte final-Properties |
Nicht unterstützt. |
Geerbte private-Properties |
Nicht unterstützt. |
Unterstützt werden die in der kompilierten Klasse selbst deklarierten Properties, einschließlich per Constructor Promotion deklarierter Properties, sowie von Elternklassen geerbte public- und protected-Properties.
Eine übersprungene Property löst keinen Fehler aus. Trifft Ihre Regel sie, bleibt die Property stillschweigend von der Interception ausgenommen: AdviceMatcher überspringt statische, readonly und mit Hooks versehene Properties, bevor überhaupt Proxy-Code generiert wird. Als Sicherheitsnetz weist auch der Property-Generator eine solche Property mit einer WeavingException zurück.
Asymmetrische Sichtbarkeit auf nicht-readonly Properties bleibt erhalten. public protected(set) string $name behält seine Modifier in der Proxy-Klasse.
Hinweise zu PHP 8.4
Abschnitt betitelt „Hinweise zu PHP 8.4“Das Framework baut die Property-Interception auf Property-Hooks von PHP 8.4 auf, und sein Container nutzt Lazy Objects von PHP 8.4 für verzögerte Services. Zwei Teile davon haben Grenzen.
Die Initialisierung von Lazy Objects lässt sich nicht abfangen
Abschnitt betitelt „Die Initialisierung von Lazy Objects lässt sich nicht abfangen“PHP 8.4 hat ReflectionClass::newLazyProxy() und ReflectionClass::newLazyGhost() für die Lazy-Initialisierung von Objekten eingeführt. Der Container des Frameworks verwendet native Lazy Proxys für seine eigenen verzögerten Services und für Behavior-Klassen (Verhaltensklassen), die per Klassenname registriert sind. Wer einen solchen Service abruft, bekommt eine typisierte, für instanceof korrekte newLazyProxy()-Instanz. Die registrierte Factory läuft erst bei der ersten echten Interaktion mit diesem Objekt.
Klassen, die PHP nicht lazy machen kann, fallen auf eine sofortige Konstruktion zurück: interne Klassen und ihre Unterklassen außer denen von stdClass, abstrakte Klassen und Enums.
Für den Moment, in dem ein Lazy Proxy seine zugrunde liegende Instanz erzeugt, gibt es keinen Call-Context; die Initialisierung von Lazy Objects selbst lässt sich daher nicht abfangen.
Zusammenfassung PHP 8.4
Abschnitt betitelt „Zusammenfassung PHP 8.4“| PHP-8.4-Feature | Unterstützung | Hinweise |
|---|---|---|
| Property-Hooks auf neuen Properties | Vom Framework generiert | Verwendet für die access(...)-Interception |
| Properties mit vorhandenen Hooks | Übersprungen | Das Framework kann nicht mit benutzerdefinierten Hooks kombinieren |
| Readonly-Properties | Übersprungen | Hooks sind auf Readonly-Properties nicht erlaubt |
| Asymmetrische Sichtbarkeit (nicht readonly) | Erhalten | Sichtbarkeits-Modifier werden in den Proxy kopiert |
Attribut #[\Deprecated] |
Übernommen | In Proxy-Methoden und -Klassen kopiert |
Lazy Objects (newLazyProxy) |
Nicht abfangbar | Kein Call-Context für die Lazy-Initialisierung |
Hinweise zu PHP 8.5
Abschnitt betitelt „Hinweise zu PHP 8.5“Die Hinweise zu PHP 8.5 beruhen auf einem Audit des Frameworks unter PHP 8.5.10 und PHP 8.6.0beta2.
Was unter PHP 8.5 funktioniert
Abschnitt betitelt „Was unter PHP 8.5 funktioniert“- Pipe-Operator
|>. Er funktioniert in kompilierten Methodenrümpfen. Methodenrümpfe werden unverändert in den Rumpf-Trait<Class>OriginalTraitverschoben, sodass jede Ausdruckssyntax von PHP 8.5 darin erhalten bleibt. clone with. Ausdrücke in kompiliertem Code funktionieren wie erwartet.#[\NoDiscard]. Das Attribut wird in die generierte Proxy-Methode kopiert, und der Call-Context gibt den Wert der abgefangenen Methode zurück. Die Warnung der Engine „return value not used“ wird für kompilierte Methoden weiterhin ausgelöst.- Attribute auf Klassenkonstanten, einschließlich
#[\Deprecated]. Klassenkonstanten bleiben zusammen mit ihren Attributen im generierten Trait. - Closures und First-Class-Callables als Parameter-Standardwerte. Sie überstehen das Kompilieren in den Signaturen der Proxy-Methoden.
- Statische asymmetrische Sichtbarkeit.
static-Properties mit asymmetrischer Sichtbarkeit (public static private(set)) funktionieren in kompilierten Klassen. Vonaccess(...)-Regeln werden sie nie erfasst. - Auflösung von
selfundparentper Reflection. Unter PHP 8.5 löstReflectionNamedType::getName()die Rückgabetypenselfundparentzu konkreten Klassennamen auf. Die Proxy-Generatoren lesen, wo verfügbar, den rohen AST-Typknoten, sodass die Schlüsselwörterselfundparentin generierten Proxys erhalten bleiben.
new in Initialisierern wird nicht abgefangen
Abschnitt betitelt „new in Initialisierern wird nicht abgefangen“Ein new-Ausdruck in einem konstanten Ausdruck wird von der Engine ausgewertet. Das betrifft den Standardwert eines Parameters oder eines per Promotion deklarierten Konstruktorparameters, den Initialisierer einer statischen Variable und ein Attribut-Argument. Der Compiler lässt diese Ausdrücke unverändert, der Code funktioniert also, aber ein initialization(...)-Behavior läuft für die damit erzeugten Objekte nicht. Abgefangen werden nur new-Ausdrücke in ausführbarem Code.
Statische Properties sind nie abfangbar
Abschnitt betitelt „Statische Properties sind nie abfangbar“Statische Properties, einschließlich der static-Properties mit asymmetrischer Sichtbarkeit aus PHP 8.5, lassen sich mit access(...)-Regeln nicht abfangen. Für statische Properties gibt es keine Property-Hooks in PHP, daher hat das Framework keinen Interception-Mechanismus für sie, und AdviceMatcher schließt sie von der Property-Interception aus. Das ist eine Beschränkung der PHP-Engine, kein Bug.
Zusammenfassung PHP 8.5
Abschnitt betitelt „Zusammenfassung PHP 8.5“| PHP-8.5-Feature | Unterstützung | Hinweise |
|---|---|---|
Pipe-Operator |> in Methodenrümpfen |
Funktioniert | Rümpfe werden unverändert in den generierten Trait verschoben |
clone with |
Funktioniert | |
#[\NoDiscard] |
Übernommen | In den Proxy kopiert; der Call-Context gibt den Wert zurück |
Attribute auf Klassenkonstanten (einschließlich #[\Deprecated]) |
Erhalten | Konstanten bleiben im generierten Trait |
| Closures und First-Class-Callables als Parameter-Standardwerte | Funktioniert | |
| Statische asymmetrische Sichtbarkeit (nicht abgefangen) | Erhalten | Statische Properties sind mit access() nie abfangbar |
Auflösung von self/parent per Reflection |
Berücksichtigt | Rohe AST-Typknoten werden bei der Proxy-Generierung verwendet |
new in Initialisierern |
Nicht abgefangen | Von der Engine ausgewertet; initialization(...)-Behaviors laufen dafür nicht |
Interception statischer Properties mit access() |
Nie | Keine Property-Hooks für statische Properties (Beschränkung der PHP-Engine) |
Kompilierumfang und Grenzen der Matching-Rules
Abschnitt betitelt „Kompilierumfang und Grenzen der Matching-Rules“Klassen, die vor dem Boot des Kernels geladen werden
Abschnitt betitelt „Klassen, die vor dem Boot des Kernels geladen werden“Kompiliert werden nur Klassen, die nach der Initialisierung des Kernels geladen werden. Eine Klasse, die vorher geladen wird, läuft ohne ihre Behaviors. Initialisieren Sie den Kernel so früh wie möglich in Ihrem Front-Controller. Framework-Bridges müssen zuerst booten; wie jede Bridge das löst, steht unter Integrationen.
Argumente lassen sich nicht matchen
Abschnitt betitelt „Argumente lassen sich nicht matchen“Die Argumentliste in einer Matching-Rule ist immer (*). Eine Regel wählt Methoden nach Klasse, Name, Modifiern, Rückgabetyp und Attributen aus, nie nach Argumentwerten oder Parametertypen. Um auf bestimmte Argumente zu reagieren, wählen Sie die Methode aus und prüfen $invocation->getArguments() im Behavior. Die vollständige Syntax steht in Behaviors & Matching-Rules.
Laufzeitkosten, die Sie kennen sollten
Abschnitt betitelt „Laufzeitkosten, die Sie kennen sollten“Diese Zahlen stammen aus dem eigenen Benchmark des Frameworks in docs/performance.md: eine kleine Shop-Anwendung mit etwa 250 Dateien, 94 kompilierten Klassen und 6 Behavior-Klassen, unter PHP 8.5.12 mit deaktiviertem JIT. Die Datei erklärt, wie gemessen wurde und wie Sie die Messungen reproduzieren.
initialization()-Regeln betreffen jedes new
Abschnitt betitelt „initialization()-Regeln betreffen jedes new“Solange eine initialization-Regel registriert ist, läuft jedes new in den generierten Dateien durch den Transformer. Eine Klasse ohne Initialisierungs-Behaviors (und mit öffentlichem Konstruktor) wird weiterhin mit einem nativen new erzeugt, das rund 130 ns mehr kostet als ein einfaches new. Eine Klasse mit Initialisierungs-Behaviors durchläuft den vollständigen Call-Context. Bevorzugen Sie Methodenregeln, wo sie ihren Zweck erfüllen.
Der Debug-Modus ist für die Entwicklung
Abschnitt betitelt „Der Debug-Modus ist für die Entwicklung“Mit 'debug' => true werden generierte Klassen über den Stream-Filter ausgeliefert, damit Xdebug-Breakpoints und magische Konstanten auf Ihre ursprünglichen Dateien zeigen, und geänderte Dateien werden automatisch neu kompiliert. Im Benchmark dauern heiße Anfragen im Debug-Modus mehr als doppelt so lange wie im Produktionsmodus. Verwenden Sie in Produktion 'debug' => false; siehe Produktion & Performance.
Upgrade von 3.x auf 4.0
Abschnitt betitelt „Upgrade von 3.x auf 4.0“Version 4.0 ersetzt den vererbungsbasierten Compiler durch einen Trait-basierten, generiert Behaviors als First-Class-Callables und baut die Caches für PHP 8.4 neu auf. Die meisten Anwendungen brauchen nur die Checkliste unten. Die Abschnitte danach beschreiben jede inkompatible Änderung. Die API-Namen darin behalten die klassischen Begriffe; die Begriffstabelle ordnet sie den hier verwendeten Wörtern zu. Die vollständige Liste der Änderungen steht im CHANGELOG.
Kurze Checkliste
Abschnitt betitelt „Kurze Checkliste“-
Verwenden Sie PHP 8.4 oder neuer, und aktualisieren Sie die Abhängigkeiten (siehe „Anforderungen und Abhängigkeiten“ unten).
-
Machen Sie jede Behavior-Methode Ihrer Behavior-Klassen
public(siehe „Behavior-Klassen“ unten). -
Registrieren Sie Behavior-Klassen mit
add()oderaddLazyService()statt mitregisterAspect(). -
Ersetzen Sie
?-Wildcards in Matching-Rules durch*, und schreiben Siedynamic(...)-Regeln um. -
Löschen Sie das Cache-Verzeichnis, und wärmen Sie es danach neu auf. Das Argument ist die Datei, die Ihren Kernel initialisiert:
Terminal-Fenster vendor/bin/aspect cache:warmup:aop public/index.php -
Wenn Sie die Doctrine-Bridge verwenden, stellen Sie die Erkennung der Entities auf
WovenEntityClassLocatorum.
Anforderungen und Abhängigkeiten
Abschnitt betitelt „Anforderungen und Abhängigkeiten“- PHP 8.4+ mit
ext-tokenizer. - Aktualisieren Sie die Abhängigkeiten mit Composer. Die erforderlichen Versionen stehen in
composer.json. psr/containerist eine neue Abhängigkeit, undnikic/php-parserwird übergoaop/parser-reflectioninstalliert.laminas/laminas-codewird nicht mehr verwendet. Proxys werden vom internen PaketGo\Proxy\Generatorgeneriert. Code, der die Generatoren des Frameworks erweitert oder sich auf mit dem Framework mitgelieferte Laminas-Generatorklassen verlassen hat, muss angepasst werden.bin/aspectbrauchtsymfony/console.
Jedes Cache-Format hat sich geändert, und keine Cache-Datei aus 3.x wird wiederverwendet.
- Proxy-Layout. Das Unterverzeichnis
_proxiesgibt es nicht mehr. Ein Proxy liegt unter dem relativen Pfad seiner Quelldatei unterhalb des Cache-Verzeichnisses, und die generierte Quelle (der ursprüngliche Klassenrumpf als Trait<Class>OriginalTrait) direkt daneben. - Class-Map.
_include.cacheordnet jede kompilierte Klasse ihrer gecachten Datei zu und wird beim Boot an Composer übergeben. Außerdem ordnet sie jede bekannte Quelldatei ihrer gecachten Datei zu (odernull, wenn nicht transformiert), für die vonINTERCEPT_INCLUDESabgefangenen Includes. Ein Cache-Verzeichnis ohne diese Datei gilt als veraltet. - Cache der Behavior-Klassen. Die serialisierten Blobs
{cacheDir}/_aspect/sha1(FQCN)sind durch gewöhnliche PHP-Dateien neben den generierten Quellen ersetzt:{appDir}/src/Aspect/LoggingAspect.phpwird als{cacheDir}/src/Aspect/LoggingAspect.cache.phpgecacht. Interceptors sind nicht mehr serialisierbar:AbstractInterceptor::__serialize(),__unserialize(),serializeAdvice()undunserializeAdvice()sind entfernt.
Die Metadatendateien tragen eine Formatversion. Mit Features::PREBUILT_CACHE wird ein Cache, den eine andere Version des Frameworks gebaut hat, mit einer Exception abgelehnt, statt zur Laufzeit neu gebaut zu werden.
Features::PREBUILT_CACHE vertraut dem Cache jetzt vollständig. Prüfungen von Verzeichnis und Schreibbarkeit, filemtime-Vergleiche, Prüfungen überwachter Ressourcen und Aktualitätsprüfungen der Caches der Behavior-Klassen entfallen allesamt. Den Cache beim Deployment neu zu bauen, liegt in der Verantwortung dessen, der deployt.
Die Option cacheFileMode wird validiert. Sie muss ein Integer zwischen 0600 und 0777 sein, der dem Eigentümer Lese- und Schreibrechte gibt. Verzeichnisse erhalten Suchrechte passend zu den Lese-Bits des Modus.
Behavior-Klassen
Abschnitt betitelt „Behavior-Klassen“Behavior-Methoden müssen public sein
Abschnitt betitelt „Behavior-Methoden müssen public sein“Generierte Proxys rufen Behaviors als First-Class-Callables auf der Instanz der Behavior-Klasse auf. Eine Methode mit #[Before], #[After], #[Around] oder #[AfterThrowing] muss daher public sein. Der Loader wirft eine AspectException für protected oder private Behavior-Methoden. Methoden, die nur #[Pointcut] tragen, dürfen jede Sichtbarkeit behalten.
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}Ein Behavior-Attribut pro Methode
Abschnitt betitelt „Ein Behavior-Attribut pro Methode“Eine Methode einer Behavior-Klasse trägt höchstens eines der Attribute #[Before], #[After], #[Around] und #[AfterThrowing]. Ein zweites wirft eine AspectException. Teilen Sie eine solche Methode in eine Methode pro Behavior auf. #[Pointcut] lässt sich weiterhin mit einem Behavior-Attribut an derselben Methode kombinieren, und Attribute, die nicht zum Framework gehören, werden ignoriert.
Behavior-Klassen registrieren
Abschnitt betitelt „Behavior-Klassen registrieren“AspectContainer::registerAspect() ist entfernt. Behavior-Klassen sind gewöhnliche Container-Services.
Vorher, in 3.x:
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}Nachher, in 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() speichert eine Factory und baut den Service beim ersten Abruf. Code, der erwartet hat, dass beim Boot eine Lazy-Proxy-Instanz existiert, muss getService() aufrufen. Eine Factory, die ein Objekt des falschen Typs zurückgibt, scheitert jetzt bei der ersten Verwendung, nicht bei der Registrierung.
AspectContainer::addResource() ist Teil des Interface. Mit onRegistration() reagieren Sie auf verzögerte Registrierungen von Services, die ein Interface implementieren.
PSR-11-Container
Abschnitt betitelt „PSR-11-Container“AspectContainer erweitert Psr\Container\ContainerInterface, Sie können den Container also an jeden Code übergeben, der einen PSR-11-Container erwartet.
AspectContainer::getValue()heißt jetztget().has()kommt aus dem PSR-Interface, mit derselben Signatur.- Eine eigene
containerClassimplementiertget()stattgetValue(), dazusetDelegate(), das den Container Ihrer Anwendung anbindet. Siehe Konfiguration & CLI.
// before$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');Eine unbekannte ID wirft ServiceNotFoundException, die Psr\Container\NotFoundExceptionInterface implementiert. getService() wirft Go\Aop\Exception\ContainerException, wenn der Eintrag keine Instanz der angeforderten Klasse ist. Diese Exception ist eine InvalidConfigurationException, die Psr\Container\ContainerExceptionInterface implementiert.
Die Umbenennung betrifft nur den Container. FieldAccess::getValue() auf Property-Call-Contexts bleibt unverändert.
Advice- und Interceptor-API
Abschnitt betitelt „Advice- und Interceptor-API“- Die Marker-Interfaces
AdviceBefore,AdviceAfterundAdviceAroundsind entfernt.AdviceverlangtgetType(): AdviceTypeEnum, mit den CasesBefore,After,AfterThrowing,AroundundIntroduction. - Die Invocation-Konstruktoren (
DynamicTraitAliasMethodInvocation,StaticTraitAliasMethodInvocation,ReflectionFunctionInvocation) verlangen ein nicht-nullbaresClosure $closureToCall. DeclareErrorist entfernt: das Attribut,DeclareErrorInterceptorundPointcutBuilder::declareError(). Geben Sie stattdessen Warnungen aus einem#[Before]- oder#[Around]-Behavior aus, oder werfen Sie dort Exceptions.
Matching-Rules
Abschnitt betitelt „Matching-Rules“Methoden mit Rückgabe per Referenz werden abgelehnt
Abschnitt betitelt „Methoden mit Rückgabe per Referenz werden abgelehnt“Das Kompilieren einer als function &name() deklarierten Methode oder Funktion schlägt mit einer WeavingException fehl, weil der Call-Context eine Kopie statt der Referenz zurückgeben würde. 3.x gab eine Kopie mit einem Notice zurück. Ergänzen Sie Regeln, die solche Methoden treffen, um && !matchReturningByReference().
Die Wildcard ? ist entfernt
Abschnitt betitelt „Die Wildcard ? ist entfernt“? in Namens- und Typmustern ist keine Wildcard für ein einzelnes Zeichen mehr, weil sie mit nullbaren Typen kollidierte. In Rückgabetyp-Mustern ist ein führendes ? eine Nullable-Markierung: ?Foo entspricht Foo|null. Ersetzen Sie ?-Wildcards durch *.
dynamic(...) ist entfernt
Abschnitt betitelt „dynamic(...) ist entfernt“Die Regel dynamic(...) ist entfernt, zusammen mit MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC und den Parametern $instanceOrScope und $arguments von Pointcut::matches(). Fangen Sie die magische Methode selbst ab, und lesen Sie den aufgerufenen Namen aus den Argumenten.
Vorher, in 3.x:
#[Around('dynamic(public Foo->save*(*))')]Nachher, in 4.0:
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}Geänderte Matching-Rules
Abschnitt betitelt „Geänderte Matching-Rules“- Rangfolge der Modifier. Durch Leerzeichen getrennte Modifier müssen alle vorhanden sein, und
|bindet stärker.final public|protectedbedeutet final UND (public ODER protected). In 3.x traf es zusätzlich jede nicht finale public-Methode. Foo+schließtFooein. Es trifft jetzt auch die Klasse oder das InterfaceFooselbst sowie Klassen, die den TraitFooverwenden. Ergänzen Sie&& !within(Foo), um den Typ selbst auszuschließen.- Attribut-Regeln treffen Unterklassen.
@execution(Attr)und die anderen Attribut-Regeln treffen auch Attribute, dieAttrerweitern. *trifft auch nichts. In Namens- und Rückgabetyp-Mustern steht*für beliebige Zeichen eines Namensteils, auch für keines. In 3.x brauchte es mindestens ein Zeichen:Sensor*übersprang die KlasseSensorselbst, undset*übersprang eine Methode namensset(). Solche Regeln treffen diese jetzt ebenfalls. Schließen Sie sie bei Bedarf mit&& !execution(public Foo->set(*))oder&& !within(Foo)aus.|-Alternativen bleiben innerhalb ihres Namensteils.Ns\A|BwähltNs\AundNs\Baus. In 3.x bedeutete esNs\Aoder die globale KlasseB. Ein Muster, das Klassen verschiedener Namespaces aufzählte (Foo\A|Bar\B), muss als zwei Regeln geschrieben werden:execution(public Foo\A->*(*)) || execution(public Bar\B->*(*)).ModifierPointcutist final und unveränderlich. Die Masken sind Konstruktorargumente, undandMatch(),orMatch()undnotMatch()geben eine neue Instanz zurück.
Compiler und generierter Code
Abschnitt betitelt „Compiler und generierter Code“Der ursprüngliche Klassenrumpf wird in einen Trait umgewandelt, <Class>OriginalTrait. Die Proxy-Klasse behält den ursprünglichen Namen, die Elternklasse und die Interfaces und verwendet diesen Trait mit privaten Aliasen <method>OriginalAlias. In 3.x erweiterte der Proxy eine umbenannte Elternklasse <Class>__AopProxied. Das betrifft Code, der sich auf diese Vererbungsschicht verlassen hat:
- Der Proxy hat keine umbenannte Elternklasse mehr.
get_parent_class(),parent::innerhalb der Klasse undinstanceof-Prüfungen sehen die ursprüngliche Elternklasse. AspectContainer::AOP_PROXIED_SUFFIXist entfernt. Verwenden SieORIGINAL_TRAIT_SUFFIX('OriginalTrait') oderORIGINAL_TRAIT_FILE_SUFFIX('OriginalTrait.php').AbstractMethodInvocation::TRAIT_ALIAS_PREFIXist durchTRAIT_ALIAS_SUFFIX('OriginalAlias') ersetzt.- Die Hooks von
InitializationAwareundStaticInitializationAwareheißen__initialization()und__staticInitialization(). self::in generiertem Code verweist auf die Proxy-Klasse, daher sindSelfValueTransformerundSelfValueVisitorentfernt.Go\Aop\Featuresist eine finale Klasse statt eines Interface. Die Konstanten sind unverändert, aber es lässt sich nicht mehr implementieren.Features::ALLkombiniert alle Flags, undAspectKernel::hasFeature()wirft bei einem unbekannten Flag.Features::PARAMETER_WIDENINGist entfernt. Löschen Sie das Flag aus Ihren Kernel-Optionen, falls Sie es übergeben haben.
Entfernte ungenutzte API
Abschnitt betitelt „Entfernte ungenutzte API“Diese öffentlichen Klassen, Methoden und Konstanten wurden innerhalb des Frameworks nicht genutzt und sind entfernt:
- Das Attribut
#[Aspect](Go\Lang\Attribute\Aspect). Das Framework hat es nie gelesen: Behavior-Klassen werden daran erkannt, dass sieGo\Aop\Aspectimplementieren. Entfernen Sie das Attribut aus Ihren Behavior-Klassen. Pointcut::KIND_TRAIT.Pointcut::KIND_ALList119statt127.Go\Proxy\Part\InterceptedConstructorGeneratorundGo\Proxy\Part\FunctionParameterList.InterceptedMethodGenerator::getBody()undsetBody(),CachePathManager::setCacheDir()undAopComposerLoader::wasInitialized().AopComposerLoader::init()gibt dasselbe Flag zurück.- Der Container-Eintrag
'kernel.options'. Verwenden SieAspectKernel::getOptions().
Umbenannte Enums und Konstanten
Abschnitt betitelt „Umbenannte Enums und Konstanten“| 3.x / frühere Entwicklungsstände von 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) |
Auch die Enums von Go\Proxy\Generator (Visibility, PropertyModifier, ClassModifier) verwenden Cases in PascalCase. Eigene Source-Transformer geben TransformerResult-Cases zurück, und Behaviors, die getAccessType() vergleichen, verwenden die neuen Case-Namen:
if ($access->getAccessType() === FieldAccessType::WRITE) {if ($access->getAccessType() === FieldAccessType::Write) {Kernel und Transformer
Abschnitt betitelt „Kernel und Transformer“AspectKernel::registerTransformers(), das Transformer-Instanzen zurückgab, ist durchregisterTransformerServices(AspectContainer $container)ersetzt, das verzögerte Container-Services registriert. Überschreiben Sie es, um die eingebauten Transformer zu ersetzen, wegzulassen, umzuordnen oder zu erweitern. Um einen anzuhängen, rufen Sie$container->addLazyService(MyTransformer::class, ...)ausconfigureAop()auf.CachingTransformerist entfernt: Die Cache-Entscheidung liegt inSourceTransformingLoader.SourceTransformingLoader::addTransformer()ist entfernt, undtransformCode()gibt das Gesamtergebnis alsTransformerResultzurück.StreamMetaData::$sourceist schreibgeschützt: Es wird bei jedem Lesen aus$tokenStreamneu aufgebaut. Eigene Transformer bearbeiten die Tokens in$tokenStreamoder ersetzen sie mitsetTokenStreamFromRawTokens().ConstructorExecutionTransformer,FilterInjectorTransformerundMagicConstantTransformersind keineSourceTransformermehr. Sie sindNodeRewriter-Regeln, angewandt in einem einzigenSyntaxTreeRewriter-Durchlauf über den Syntaxbaum. Dieser Durchlauf ist ein Service des Frameworks: Er eröffnet die Kette vorWeavingTransformer, auch wennregisterTransformerServices()überschrieben ist.- Eigene
SourceTransformerwerden wie bisher registriert. Um einzelne Knoten umzuschreiben, registrieren Sie einenNodeRewriter-Service statt eines Transformers, der den Baum selbst durchläuft. Wie Sie die Transformations-Pipeline erweitern, steht unter Konfiguration & CLI.
Finale und interne Klassen
Abschnitt betitelt „Finale und interne Klassen“Klassen, die nie zum Erweitern gedacht waren, sind jetzt final:
Go\Core\Container,Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\Instrument\ClassLoading\AopComposerLoader,SourceTransformingLoader,Go\Instrument\PathResolver- die Transformer
WeavingTransformer,FilterInjectorTransformer,MagicConstantTransformerundStreamMetaData - die Proxy-Generatoren
EnumProxyGenerator,TraitProxyGeneratorundFunctionProxyGenerator - die Attribute
#[Before],#[After],#[Around],#[AfterThrowing],#[Pointcut]und#[DeclareParents]
Go\Lang\Attribute\AbstractInterceptor ist abstract. Klassen, die nur zur Maschinerie des Frameworks gehören, sind als @internal markiert und fallen nicht unter die BC-Zusagen: AdviceMatcher, AspectLoader, CachedAspectLoader, CachePathManager, CacheWarmer, Enumerator, InterceptorInjector, The und NativeLazyProxy.
Ersetzen Sie Unterklassen dieser Klassen durch Komposition oder durch einen eigenen Container oder Transformer, registriert in configureAop() oder registerTransformerServices().
Exceptions
Abschnitt betitelt „Exceptions“Jede vom Framework geworfene Exception implementiert Go\Aop\Exception\ExceptionInterface, sodass ein einziges catch jeden seiner Fehler behandelt. Mehrere Stellen werfen jetzt einen anderen Typ:
| Situation | 3.x | 4.0 |
|---|---|---|
| Ungültige Kernel-Optionen, Container-Registrierungen, Konsoleneingaben | RuntimeException, InvalidArgumentException, UnexpectedValueException |
InvalidConfigurationException (eine InvalidArgumentException) |
| Ungültige Matching-Rule | UnexpectedValueException, InvalidArgumentException |
PointcutSyntaxException (eine AspectException) |
| Unbekannte Container-ID | OutOfBoundsException |
ServiceNotFoundException (eine OutOfBoundsException und ein PSR-11-NotFoundExceptionInterface) |
Container-Eintrag des falschen Typs in getService() |
InvalidArgumentException |
ContainerException (eine InvalidConfigurationException und ein PSR-11-ContainerExceptionInterface) |
| Kompilieren, Proxy-Generierung, Schreiben des Caches | RuntimeException, LogicException, InvalidArgumentException |
WeavingException (eine RuntimeException) |
| Behavior, das sich nicht cachen lässt | Go\Core\Cache\NotCompilableException |
Go\Aop\Exception\NotCompilableException |
| Ungültige Behavior-Klasse, Laufzeitfehler des Call-Context | Go\Aop\AspectException |
Go\Aop\Exception\AspectException, Go\Aop\Exception\InvocationException |
Wo Sie die oben genannten SPL-Typen abgefangen haben, fangen Sie ExceptionInterface oder die neuen Typen ab.
Doctrine-Bridge
Abschnitt betitelt „Doctrine-Bridge“Die Bridge schreibt Entity-Metadaten nicht mehr um. Der Mapped-Superclass-Workaround aus 3.x galt nur für die vererbungsbasierte Engine, und Doctrine mappt eine kompilierte Entity so, wie sie ist, korrekt. Konfigurieren Sie stattdessen zwei Dinge (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());Konsole
Abschnitt betitelt „Konsole“Die Befehle deklarieren ihre Namen mit #[AsCommand] und werden von bin/aspect lazy geladen. Jeder Befehl gibt Command::SUCCESS oder Command::FAILURE zurück.
- In 3.x gab
debug:weavingdie rohe Anzahl der Fehler zurück. Wenn sich ein Skript auf diese Zahl verlassen hat, prüfen Sie stattdessen den Exit-Code. cache:warmup:aopschlägt fehl, wenn sich eine Datei nicht kompilieren lässt; ein Deploy-Skript, das Warm-up-Fehler ignoriert hat, bricht jetzt also an dieser Stelle ab. Ergänzen Sie--fail-fast, um beim ersten Fehler anzuhalten:
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast© 2026 Alexander Lisachenko
