Zum Inhalt springen
Dokumentation

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“

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.

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.

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.

getArguments() listet die Argumente nach Position. Ein variadischer Parameter per Referenz (&...$values) wird an die ursprüngliche Methode per Wert übergeben.

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 Konstruktoren
  • forward_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.

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.

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.

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.

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

Die Hinweise zu PHP 8.5 beruhen auf einem Audit des Frameworks unter PHP 8.5.10 und PHP 8.6.0beta2.

  • Pipe-Operator |>. Er funktioniert in kompilierten Methodenrümpfen. Methodenrümpfe werden unverändert in den Rumpf-Trait <Class>OriginalTrait verschoben, 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. Von access(...)-Regeln werden sie nie erfasst.
  • Auflösung von self und parent per Reflection. Unter PHP 8.5 löst ReflectionNamedType::getName() die Rückgabetypen self und parent zu konkreten Klassennamen auf. Die Proxy-Generatoren lesen, wo verfügbar, den rohen AST-Typknoten, sodass die Schlüsselwörter self und parent in generierten Proxys erhalten bleiben.

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, 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.

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)

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.

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.

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.

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.

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.

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.

  1. Verwenden Sie PHP 8.4 oder neuer, und aktualisieren Sie die Abhängigkeiten (siehe „Anforderungen und Abhängigkeiten“ unten).

  2. Machen Sie jede Behavior-Methode Ihrer Behavior-Klassen public (siehe „Behavior-Klassen“ unten).

  3. Registrieren Sie Behavior-Klassen mit add() oder addLazyService() statt mit registerAspect().

  4. Ersetzen Sie ?-Wildcards in Matching-Rules durch *, und schreiben Sie dynamic(...)-Regeln um.

  5. 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
  6. Wenn Sie die Doctrine-Bridge verwenden, stellen Sie die Erkennung der Entities auf WovenEntityClassLocator um.

  • PHP 8.4+ mit ext-tokenizer.
  • Aktualisieren Sie die Abhängigkeiten mit Composer. Die erforderlichen Versionen stehen in composer.json.
  • psr/container ist eine neue Abhängigkeit, und nikic/php-parser wird über goaop/parser-reflection installiert.
  • laminas/laminas-code wird nicht mehr verwendet. Proxys werden vom internen Paket Go\Proxy\Generator generiert. Code, der die Generatoren des Frameworks erweitert oder sich auf mit dem Framework mitgelieferte Laminas-Generatorklassen verlassen hat, muss angepasst werden.
  • bin/aspect braucht symfony/console.

Jedes Cache-Format hat sich geändert, und keine Cache-Datei aus 3.x wird wiederverwendet.

  • Proxy-Layout. Das Unterverzeichnis _proxies gibt 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.cache ordnet 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 (oder null, wenn nicht transformiert), für die von INTERCEPT_INCLUDES abgefangenen 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.php wird als {cacheDir}/src/Aspect/LoggingAspect.cache.php gecacht. Interceptors sind nicht mehr serialisierbar: AbstractInterceptor::__serialize(), __unserialize(), serializeAdvice() und unserializeAdvice() 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.

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.

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

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.

AspectContainer::registerAspect() ist entfernt. Behavior-Klassen sind gewöhnliche Container-Services.

Vorher, in 3.x:

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

Nachher, in 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() 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.

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 jetzt get().
  • has() kommt aus dem PSR-Interface, mit derselben Signatur.
  • Eine eigene containerClass implementiert get() statt getValue(), dazu setDelegate(), das den Container Ihrer Anwendung anbindet. Siehe Konfiguration & CLI.
4.0
// 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.

  • Die Marker-Interfaces AdviceBefore, AdviceAfter und AdviceAround sind entfernt. Advice verlangt getType(): AdviceTypeEnum, mit den Cases Before, After, AfterThrowing, Around und Introduction.
  • Die Invocation-Konstruktoren (DynamicTraitAliasMethodInvocation, StaticTraitAliasMethodInvocation, ReflectionFunctionInvocation) verlangen ein nicht-nullbares Closure $closureToCall.
  • DeclareError ist entfernt: das Attribut, DeclareErrorInterceptor und PointcutBuilder::declareError(). Geben Sie stattdessen Warnungen aus einem #[Before]- oder #[Around]-Behavior aus, oder werfen Sie dort Exceptions.

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().

? 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 *.

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:

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

Nachher, in 4.0:

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • Rangfolge der Modifier. Durch Leerzeichen getrennte Modifier müssen alle vorhanden sein, und | bindet stärker. final public|protected bedeutet final UND (public ODER protected). In 3.x traf es zusätzlich jede nicht finale public-Methode.
  • Foo+ schließt Foo ein. Es trifft jetzt auch die Klasse oder das Interface Foo selbst sowie Klassen, die den Trait Foo verwenden. 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, die Attr erweitern.
  • * 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 Klasse Sensor selbst, und set* übersprang eine Methode namens set(). 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|B wählt Ns\A und Ns\B aus. In 3.x bedeutete es Ns\A oder die globale Klasse B. 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->*(*)).
  • ModifierPointcut ist final und unveränderlich. Die Masken sind Konstruktorargumente, und andMatch(), orMatch() und notMatch() geben eine neue Instanz zurück.

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 und instanceof-Prüfungen sehen die ursprüngliche Elternklasse.
  • AspectContainer::AOP_PROXIED_SUFFIX ist entfernt. Verwenden Sie ORIGINAL_TRAIT_SUFFIX ('OriginalTrait') oder ORIGINAL_TRAIT_FILE_SUFFIX ('OriginalTrait.php').
  • AbstractMethodInvocation::TRAIT_ALIAS_PREFIX ist durch TRAIT_ALIAS_SUFFIX ('OriginalAlias') ersetzt.
  • Die Hooks von InitializationAware und StaticInitializationAware heißen __initialization() und __staticInitialization().
  • self:: in generiertem Code verweist auf die Proxy-Klasse, daher sind SelfValueTransformer und SelfValueVisitor entfernt.
  • Go\Aop\Features ist eine finale Klasse statt eines Interface. Die Konstanten sind unverändert, aber es lässt sich nicht mehr implementieren. Features::ALL kombiniert alle Flags, und AspectKernel::hasFeature() wirft bei einem unbekannten Flag.
  • Features::PARAMETER_WIDENING ist entfernt. Löschen Sie das Flag aus Ihren Kernel-Optionen, falls Sie es übergeben haben.

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 sie Go\Aop\Aspect implementieren. Entfernen Sie das Attribut aus Ihren Behavior-Klassen.
  • Pointcut::KIND_TRAIT. Pointcut::KIND_ALL ist 119 statt 127.
  • Go\Proxy\Part\InterceptedConstructorGenerator und Go\Proxy\Part\FunctionParameterList.
  • InterceptedMethodGenerator::getBody() und setBody(), CachePathManager::setCacheDir() und AopComposerLoader::wasInitialized(). AopComposerLoader::init() gibt dasselbe Flag zurück.
  • Der Container-Eintrag 'kernel.options'. Verwenden Sie AspectKernel::getOptions().
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) {
  • AspectKernel::registerTransformers(), das Transformer-Instanzen zurückgab, ist durch registerTransformerServices(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, ...) aus configureAop() auf.
  • CachingTransformer ist entfernt: Die Cache-Entscheidung liegt in SourceTransformingLoader. SourceTransformingLoader::addTransformer() ist entfernt, und transformCode() gibt das Gesamtergebnis als TransformerResult zurück.
  • StreamMetaData::$source ist schreibgeschützt: Es wird bei jedem Lesen aus $tokenStream neu aufgebaut. Eigene Transformer bearbeiten die Tokens in $tokenStream oder ersetzen sie mit setTokenStreamFromRawTokens().
  • ConstructorExecutionTransformer, FilterInjectorTransformer und MagicConstantTransformer sind keine SourceTransformer mehr. Sie sind NodeRewriter-Regeln, angewandt in einem einzigen SyntaxTreeRewriter-Durchlauf über den Syntaxbaum. Dieser Durchlauf ist ein Service des Frameworks: Er eröffnet die Kette vor WeavingTransformer, auch wenn registerTransformerServices() überschrieben ist.
  • Eigene SourceTransformer werden wie bisher registriert. Um einzelne Knoten umzuschreiben, registrieren Sie einen NodeRewriter-Service statt eines Transformers, der den Baum selbst durchläuft. Wie Sie die Transformations-Pipeline erweitern, steht unter Konfiguration & CLI.

Klassen, die nie zum Erweitern gedacht waren, sind jetzt final:

  • Go\Core\Container, Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\Instrument\ClassLoading\AopComposerLoader, SourceTransformingLoader, Go\Instrument\PathResolver
  • die Transformer WeavingTransformer, FilterInjectorTransformer, MagicConstantTransformer und StreamMetaData
  • die Proxy-Generatoren EnumProxyGenerator, TraitProxyGenerator und FunctionProxyGenerator
  • 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().

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.

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());

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:weaving die rohe Anzahl der Fehler zurück. Wenn sich ein Skript auf diese Zahl verlassen hat, prüfen Sie stattdessen den Exit-Code.
  • cache:warmup:aop schlä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:
Terminal-Fenster
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast

© 2026 Alexander Lisachenko