Zum Inhalt springen
Dokumentation

Konfiguration & CLI

Konfigurieren Sie den Kernel, wählen Sie Feature-Flags, versorgen Sie Behavior-Klassen mit Abhängigkeiten aus Ihrem Anwendungscontainer und nutzen Sie die Konsole.

Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen

Alles, was das Framework über Ihre Anwendung wissen muss, läuft über einen einzigen Aufruf: init() auf Ihrem Kernel. Diese Seite führt jede Option auf, die der Kernel akzeptiert, die Feature-Flags, wie Behavior-Klassen (Verhaltensklassen) ihre Abhängigkeiten aus Ihrem Anwendungscontainer beziehen, und die Konsole vendor/bin/aspect, mit der Sie den Cache bauen und untersuchen.

Ihr Kernel erweitert Go\Core\AspectKernel und registriert in configureAop() die Behavior-Klassen, in der API Aspects (Aspekte) genannt (siehe die Begriffstabelle):

app/ApplicationAspectKernel.php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect());
}
}

Sie initialisieren ihn einmal, meist im Front-Controller, direkt nach dem Composer-Autoloader:

public/index.php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
]);

Nur die folgenden Optionen werden akzeptiert. Ein unbekannter Schlüssel, eine unbekannte containerClass oder ein unbekanntes Feature-Bit wirft Go\Aop\Exception\InvalidConfigurationException, ein Tippfehler fällt also beim Booten auf, statt ignoriert zu werden.

Option Typ Standard Zweck
cacheDir string keiner, Pflicht Verzeichnis für kompilierte Quellen, Proxys, Advisor-Caches und die Class-Map.
appDir string das Verzeichnis, das vendor/ enthält Wurzelverzeichnis der Anwendung. Die Cache-Pfade spiegeln die Quellpfade relativ dazu, und nur Dateien darunter werden kompiliert.
debug bool false Entwicklungsmodus: Änderungen an der Kernel-Datei und an den Dateien der Behavior-Klassen invalidieren den Cache, und jede Klasse und jedes include wird über den kompilierenden Stream-Filter des Frameworks geladen. Mit false werden kompilierte Klassen über die Class-Map von Composer aus dem Cache geladen. Verwenden Sie in Produktion false.
includePaths string[] [] (alles unterhalb von appDir) Verzeichnisse, die kompiliert werden. Halten Sie die Liste eng: Vendor-Code zu kompilieren ist langsam und selten nötig.
excludePaths string[] [] Verzeichnisse, die nie kompiliert werden. Das Cache-Verzeichnis, das Framework selbst und seine Laufzeitabhängigkeiten (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) sind immer ausgeschlossen.
features int 0 Bitmaske aus Go\Aop\Features-Flags, siehe nächster Abschnitt.
cacheFileMode int 0770 abzüglich der umask Berechtigungen der Cache-Dateien. Muss zwischen 0600 und 0777 liegen und dem Eigentümer Lese- und Schreibrechte geben; Verzeichnisse erhalten die passenden Such-Bits.
containerClass class-string Go\Core\Container Implementierung des Containers des Kernels. Muss Go\Core\AspectContainer implementieren (ein PSR-11-ContainerInterface).
parsedFilesLimit int 100 Anzahl geparster Quelldateien (Syntaxbäume, je etwa 0,2 MB), die goaop/parser-reflection beim Kompilieren im Speicher hält. Muss eine positive Ganzzahl sein: Mehr bedeutet weniger erneutes Parsen, weniger bedeutet weniger Speicher. Sie ersetzt ein Limit, das vor init() mit ReflectionEngine::setMaximumCachedFiles() gesetzt wurde, und ist der Standardwert von cache:warmup:aop --cached-files.

Feature-Flags sind Konstanten der finalen Klasse Go\Aop\Features. Kombinieren Sie sie mit |:

public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,
]);

Features::ALL kombiniert alle Flags. AspectKernel::hasFeature() sagt Ihnen, ob ein Flag gesetzt ist, und wirft bei einem unbekannten Flag eine Exception.

Flag Verwenden Sie es, wenn
INTERCEPT_INCLUDES Ihre Anwendung Code mit include/require statt über Composer lädt.
PREBUILT_CACHE Sie den Cache beim Deployment bauen und Anfragen ihm vollständig vertrauen sollen. Die Einstellung für Produktion.
PARTIAL_REFLECTION eine Klasse, die Sie kompilieren wollen, etwas erweitert oder implementiert, das das Framework nicht finden kann.

Leitet include und require in kompilierten Dateien durch den Compiler. Verwenden Sie es für Legacy-Code, der nicht von Composer geladen wird.

Vertraut dem beim Deployment gebauten Cache vollständig. Der Kernel überspringt die Prüfungen von Cache-Verzeichnis und Schreibbarkeit, die Vergleiche der filemtime von Quellen, die Prüfungen verfolgter Ressourcen und die Aktualitätsprüfungen der Advisor-Caches. Eine Anfrage kompiliert nie und schreibt nie in das Cache-Verzeichnis, sie funktioniert also auf schreibgeschützten Dateisystemen.

Die Kehrseite: Der Cache muss vollständig sein. Dateien, die der Compiler nie übernimmt (außerhalb der Include-Pfade, ausgeschlossen, keine .php-Datei, zum Beispiel ein eingebundenes Template), werden unverändert geladen. Alles andere unterhalb der Include-Pfade muss einen Eintrag im Cache haben.

cache:warmup:aop selbst vertraut dem Cache, den es baut, nicht. Über einem bestehenden Verzeichnis kompiliert es jede Datei neu, deren Quelle sich geändert hat (Größe oder Änderungszeit). Seine Loader-Datei darf Klassen, die der Cache noch nicht kennt, laden, bevor der Build beginnt: Sie werden dort unkompiliert geladen und vom Build kompiliert.

Kompiliert eine Klasse, deren Elternklasse, Interface oder Trait sich nicht finden lässt: eines, das von zur Laufzeit generiertem Code, durch ein class_alias() oder in einer Datei außerhalb des Composer-Autoloaders deklariert wird. Die Klasse wird mit ihren eigenen Methoden und Properties und denen ihrer verfügbaren Vorfahren gematcht und kompiliert. Member, die von einem fehlenden Vorfahren geerbt sind, werden nicht abgefangen.

Ohne das Flag lässt sich eine solche Klasse nicht kompilieren. Schalten Sie es ein, wenn Sie auf diesen Fehler stoßen.

Funktions- und Initialisierungsregeln brauchen kein Flag

Abschnitt betitelt „Funktions- und Initialisierungsregeln brauchen kein Flag“

Das Framework aktiviert die Mechanik für diese Matching-Rules (Auswahlregeln) anhand der registrierten Behavior-Klassen, die lazy registrierten eingeschlossen. Sie setzen nichts in features:

  • Eine execution(Namespace\function(*))-Regel fügt den passenden Namespaces Funktions-Proxys hinzu.
  • Eine initialization(...)-Regel schaltet das Umschreiben von new Foo(...)-Ausdrücken in kompilierten Dateien ein. Solange eine registriert ist, läuft jedes umgeschriebene new durch den Interceptor, beschränken Sie solche Regeln also auf den Code, der sie braucht.

Die Syntax der Matching-Rules steht unter Behaviors & Matching-Rules.

Der Container des Kernels ist ein PSR-11-Container (Go\Core\AspectContainer erweitert Psr\Container\ContainerInterface). Er kann an den Container Ihrer Anwendung delegieren: Symfony, Laravel, PHP-DI oder jeden anderen PSR-11-Container. get(), getService() und has() greifen für IDs, die nicht im Container des Kernels registriert sind, auf den Delegate zurück.

Der Kernel wird initialisiert, bevor die Anwendung ihren Container baut. Deshalb registrieren Sie Behavior-Klassen wie gewohnt und lassen sie ihre Abhängigkeiten lazy auflösen:

app/ApplicationAspectKernel.php
protected function configureAop(AspectContainer $container): void
{
// Runs when one of its behaviors first runs, after the application container is attached
$container->addLazyService(
MonitorAspect::class,
static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)),
);
// or take the whole behavior class from the application container, by the id it has there
// $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));
}

Sobald der Anwendungscontainer existiert, zum Beispiel direkt nachdem der Kernel Ihres Frameworks gebootet hat, binden Sie ihn an:

ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);

Der Compile-Step (Kompilierschritt) und das Cache-Warm-up brauchen nur die Behavior-Klasse selbst. Sie laufen vor setDelegate(), auch in vendor/bin/aspect, und erzeugen nie eine Instanz davon. Die Factory läuft, wenn eines ihrer Behaviors (Verhalten) zum ersten Mal läuft; eine Abhängigkeit, die dann noch fehlt, wirft ServiceNotFoundException.

Die Bridges für Symfony, Laravel und Yii 3 werden unter Integrationen behandelt.

  • Eine Factory fragt den Container des Kernels nie nach ihrer eigenen ID. Diese ID löst auf die Behavior-Klasse auf, die gerade gebaut wird. Holen Sie die Instanz unter der ID, die sie dort hat, aus dem Anwendungscontainer, oder bauen Sie sie aus ihren Abhängigkeiten.
  • Behavior-Klassen werden im Delegate nie automatisch gefunden. Ein PSR-11-Container lässt sich nicht introspektieren: Es gibt keinen Standardweg, Services nach Interface oder Tag zu suchen. Jede Behavior-Klasse wird in configureAop() registriert. Eine Bridge für ein bestimmtes Framework kann Services nach Tag oder Interface aus dem eigenen Container einsammeln und mit addLazyService() registrieren.
  • Der Compile-Step erzeugt nie eine Instanz einer Behavior-Klasse. Er liest die Behavior-Klasse, und der generierte Code verweist auf jedes Behavior über Klassen- und Methodennamen. Jede Behavior-Klasse, auch eine ohne Instanz-Properties (die PHP nicht lazy machen kann), wird von ihrer Factory erzeugt, wenn eines ihrer Behaviors zum ersten Mal läuft, sobald der Anwendungscontainer angebunden ist.
  • Das Erzeugen einer Behavior-Klasse darf keines ihrer eigenen Behaviors auslösen. Hängt die Behavior-Klasse von einem Service ab, dessen Konstruktion eines ihrer Behaviors abfängt (den Konstruktor des Service oder eine Methode, die der Konstruktor aufruft), würde dieses Behavior auf einer Instanz laufen, die es noch nicht gibt. Der Interceptor meldet das mit einer AspectCircularReferenceException, die die Behavior-Klasse, den abgefangenen Aufruf und die Aufrufe von der Erzeugung bis zum Behavior nennt. Injizieren Sie die Abhängigkeit lazy (ein Lazy Service, eine Closure oder ein Service-Locator) oder grenzen Sie die Matching-Rule so ein, dass die Behavior-Klasse die Erzeugung ihrer eigenen Abhängigkeiten nicht abfängt.

Um den Container des Kernels zu ersetzen, übergeben Sie Ihre Klasse als containerClass. Sie muss Go\Core\AspectContainer implementieren, also die PSR-11-Methoden get() und has() sowie setDelegate(). Eine unbekannte ID wirft ServiceNotFoundException, die Psr\Container\NotFoundExceptionInterface implementiert.

Die Option debug schaltet zwischen zwei Modi um. Ihre Behavior-Klassen und Matching-Rules sind in beiden dieselben.

'debug' => true 'debug' => false
Laden der Klassen Jede Klasse und jedes include läuft durch den kompilierenden Stream-Filter. Kompilierte Klassen kommen über die Class-Map von Composer aus dem Cache.
Geänderte Quelle, Behavior-Klasse oder Kernel-Datei Wird bei der nächsten Anfrage neu kompiliert. Der Cache wird unverändert ausgeliefert.
Neuaufbau des Caches Nicht nötig. Bei jedem Deployment, mit cache:warmup:aop.
Einsatz Lokale Entwicklung. Produktion. Ergänzen Sie Features::PREBUILT_CACHE.

In der Entwicklung gibt es keinen Build-Schritt: Klasse oder Behavior bearbeiten, neu laden, und das Framework kompiliert neu, was sich geändert hat. Breakpoints funktionieren in Ihrem ursprünglichen Code.

In Produktion übergibt das Framework die Class-Map des Caches an Composer, und Parser und Transformer werden bei warmen Anfragen gar nicht erst geladen. Mit PREBUILT_CACHE obendrauf überspringt eine Anfrage außerdem jede Prüfung von Quelldateien und Cache-Aktualität. Wie Sie das weiter optimieren (OPcache, Preloading, Container), steht unter Produktion & Performance.

cacheDir ist die einzige Pflichtoption. Das Verzeichnis enthält:

  • die kompilierten Quellen: jeden ursprünglichen Klassenrumpf als Trait <Class>OriginalTrait, unter dem relativen Pfad seiner Quelldatei;
  • die Proxys, neben den kompilierten Quellen, unter dem ursprünglichen Klassennamen;
  • die Advisor-Caches Ihrer Behavior-Klassen, als gewöhnliche PHP-Dateien neben den kompilierten Quellen;
  • die Metadaten, darunter _include.cache, die Class-Map, die an Composer übergeben wird;
  • _preload.php, wenn Sie den Cache mit cache:warmup:aop --preload bauen.

Gut zu wissen:

  • Es spiegelt appDir. Die Cache-Pfade sind relativ zum Wurzelverzeichnis der Anwendung, und Pfade in den Metadaten werden relativ zu __DIR__ gespeichert, sodass der Cache gültig bleibt, wenn das Anwendungsverzeichnis verschoben wird.
  • Es wird nie kompiliert. Das Cache-Verzeichnis ist immer ausgeschlossen, egal was Sie in excludePaths eintragen.
  • Die Berechtigungen kommen aus cacheFileMode. Der Standard ist 0770 abzüglich der umask. Bauen Sie den Cache als der Benutzer, der die Anfragen bedient, oder für ihn.
  • Löschen Sie es beim Upgrade von 3.x. Keine Cache-Datei aus 3.x wird wiederverwendet, und mit PREBUILT_CACHE wird ein Cache, der von einer anderen Version des Frameworks gebaut wurde, abgewiesen.
Terminal-Fenster
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/bin/aspect benötigt symfony/console (^7.4 || ^8.0). Installieren Sie es mit Composer, falls Ihre Anwendung es noch nicht hat.

Jeder Befehl erwartet den Pfad zu der Datei, die Ihren Kernel initialisiert, meist den Front-Controller oder eine Bootstrap-Datei. Diese Datei wird ausgeführt, der Befehl sieht den Kernel also mit denselben Optionen wie Ihre Anwendung. Innerhalb einer Anwendung, die ihren Kernel bereits initialisiert hat (die Konsole einer Framework-Integration, in der die Befehle als Services registriert sind), lassen Sie das Argument weg: Die Befehle verwenden den Kernel des Prozesses.

Jeder Befehl gibt Command::SUCCESS oder Command::FAILURE zurück. Prüfen Sie in Skripten den Exit-Code.

Befehl Zweck
cache:warmup:aop Kompiliert jede Datei unterhalb der Include-Pfade in den Cache.
cache:warmup:opcache Befüllt opcache.file_cache mit dem Cache des Frameworks und dem, was eine Anfrage lädt.
debug:aspect Listet die registrierten Behavior-Klassen und ihre Behaviors auf.
debug:advisor Listet die Advisors auf (jedes Behavior mit seiner Matching-Rule) oder die abgefangenen Aufrufe, die ein Advisor trifft.
debug:weaving Wärmt den Cache zweimal auf und meldet Proxys, die unterschiedlich generiert werden.
Terminal-Fenster
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

Der Befehl kompiliert jede Datei unterhalb von includePaths (abzüglich excludePaths) und schreibt die kompilierten Dateien, die Proxys, die Advisor-Caches und die Metadaten. Er zeigt einen Fortschrittsbalken. Jede Datei, die sich nicht kompilieren lässt, meldet er auf stderr und endet mit einem Exit-Code ungleich null, sodass ein Deploy-Skript oder ein docker build dort abbricht, statt einen unvollständigen Cache auszuliefern.

Option Standard Zweck
--workers=N 1 (kompiliert im Prozess des Befehls) Kompiliert in N parallelen Worker-Prozessen. Verwenden Sie die Anzahl der CPUs.
--cached-files=N die Kernel-Option parsedFilesLimit, 100 Anzahl geparster Dateien, die jeder Prozess im Speicher hält.
--fail-fast aus Hält bei der ersten Datei an, die sich nicht kompilieren lässt.
--cache-dir=DIR das cacheDir des Kernels Baut den Cache in einem anderen Verzeichnis von Grund auf, während Kernel und Worker weiter ihr eigenes verwenden.
--preload[=FILE] aus Schreibt zusätzlich das opcache.preload-Skript des Caches: _preload.php im Cache-Verzeichnis oder FILE.
-v aus Gibt jede Datei aus statt nur des Fortschrittsbalkens.

Hinweise zu den Optionen:

  • --cache-dir ist der Weg, auf dem ein Deployment den Cache des nächsten Releases neben dem laufenden vorbereitet und ihn dann atomar umschaltet, zum Beispiel per Symlink-Tausch. Ein so gebauter Cache ist vollständig und unabhängig vom Ablageort, auch wenn ein Produktions-Kernel ihn baut, während sein eigener Cache warm ist: Der Compiler liest immer die ursprünglichen Quellen, nie die kompilierten Dateien, die Composer ausliefert.
  • --preload muss in seiner Form ohne Wert nach dem Loader-Argument stehen, sonst nimmt es den Loader als Wert. Das Skript verlinkt beim Start von PHP jede kompilierte Klasse und jede nicht transformierte Klasse, die der Cache kennt; Klassen mit einem Behavior bei der statischen Initialisierung bleiben dem Autoloader überlassen. Es enthält keinen absoluten Pfad und listet genau die Klassen dieses Caches, deshalb bauen Sie es mit dem Cache neu. Die Einrichtung des Preloadings behandelt Produktion & Performance.
  • Über einem bestehenden Verzeichnis kompiliert der Befehl jede Datei neu, deren Quelle sich geändert hat (Größe oder Änderungszeit), und behält die übrigen, auch mit PREBUILT_CACHE. Beginnen Sie mit einem leeren Verzeichnis, wenn der Cache genau das aktuelle Release enthalten soll.
Terminal-Fenster
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

Kompiliert in opcache.file_cache, was eine Anfrage in Produktion lädt: den Cache des Frameworks, die Class-Map und die per Autoload geladenen Dateien von Composer, die nicht transformierten Quellen, den Loader und die Einstiegspunkte. Ein neuer PHP-FPM-Master- oder CLI-Prozess liest dann kompilierte Skripte von der Festplatte, statt sie zu kompilieren.

Option Zweck
--file-cache=DIR Das Verzeichnis von opcache.file_cache. Es muss mit dem konfigurierten übereinstimmen.
--entry=FILE Ein zu kompilierender Einstiegspunkt. Wiederholen Sie die Option für mehrere Dateien.

Kompilierte Skripte werden nur von einem Prozess auf die Festplatte geschrieben, der mit -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR gestartet wurde. Läuft der Befehl ohne diese Optionen, gibt er den genauen Befehl aus, den Sie ausführen müssen.

Der File-Cache gehört zum PHP-Build und zu den absoluten Pfaden der Dateien. Führen Sie den Befehl im finalen Image aus, nach cache:warmup:aop, mit dem PHP-Binary, das die Anfragen bedient. Der Cache des Frameworks, der Loader und die Einstiegspunkte müssen sich kompilieren lassen, sonst schlägt der Befehl fehl; Dateien aus der Class-Map von Composer, die sich nicht kompilieren lassen, werden aufgelistet und übersprungen.

Terminal-Fenster
vendor/bin/aspect debug:aspect public/index.php

Listet die registrierten Behavior-Klassen und ihre Behaviors auf. Der Befehl akzeptiert außerdem die Option --aspect=....

Terminal-Fenster
vendor/bin/aspect debug:advisor public/index.php

Listet die Advisors auf. Mit --advisor=... zeigt er die abgefangenen Aufrufe, die dieser Advisor trifft. Daran sehen Sie, ob Ihre Matching-Rule die Methoden auswählt, die Sie erwarten.

Terminal-Fenster
vendor/bin/aspect debug:weaving public/index.php

Wärmt den Cache zweimal auf und meldet Proxys, die zwischen den beiden Durchläufen unterschiedlich generiert werden. Ein Unterschied deutet auf eine nicht deterministische Behavior-Klasse hin.

Terminal-Fenster
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. Leeren Sie das Cache-Verzeichnis.
  2. Wärmen Sie den Cache mit cache:warmup:aop auf. Der Befehl schlägt fehl, wenn sich eine Datei nicht kompilieren lässt, sodass das Deployment abbricht, statt einen unvollständigen Cache auszuliefern. Große Projekte kompilieren mit --workers parallel schneller.
  3. Starten Sie mit 'debug' => false und Features::PREBUILT_CACHE.
public/index.php
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
'features' => Features::PREBUILT_CACHE,
]);

Bauen Sie den Cache neu, sobald sich der Code, die Behavior-Klassen, die Kernel-Optionen oder composer.lock ändern. In der Praxis heißt das: bei jedem Deployment. Der Entwicklungsmodus braucht keinen Neuaufbau.

OPcache-Tuning, Preloading, die Flags des Composer-Autoloaders und das Bauen des Caches in ein Docker-Image finden Sie unter Produktion & Performance. Das Upgrade von 3.x, einschließlich der Änderung des Cache-Formats, steht unter Einschränkungen & Upgrade.

© 2026 Alexander Lisachenko