Zum Inhalt springen
Dokumentation · Integrationen

Yii3

Yii3-Integration mit goaop/goaop-yii3-bridge 1.0: Anbindung über yiisoft/config, getaggte Behavior-Klassen und ./yii aop:warmup.

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

Die Bridge goaop/goaop-yii3-bridge 1.0 klinkt sich in yiisoft/config ein. Ihre Behavior-Klassen (Verhaltensklassen) sind reguläre Services des Yii-Containers, und die Engine löst jede erst auf, wenn eines ihrer Behaviors (Verhalten) zum ersten Mal läuft.

  • PHP 8.4 oder neuer
  • Yii3-Pakete: yiisoft/config, yiisoft/di, yiisoft/aliases (wie im Anwendungs-Template)
  • goaop/framework ^4.0 (Behaviors per Attribut deklariert)
Terminal-Fenster
composer require goaop/goaop-yii3-bridge

Das Plugin von yiisoft/config übernimmt die Konfiguration der Bridge. Wenn Sie sie bei deaktiviertem Plugin installiert haben, führen Sie composer yii-config-rebuild aus.

public/index.php
use App\Environment;
use Go\Yii3\GoAopBridge\AopBootstrap;
use Yiisoft\Yii\Runner\Http\HttpApplicationRunner;
// ...
$runner = new HttpApplicationRunner(
rootPath: dirname(__DIR__),
debug: Environment::appDebug(),
checkEvents: Environment::appDebug(),
environment: Environment::appEnv(),
);
AopBootstrap::init($runner->getConfig(), rootPath: dirname(__DIR__));
$runner->run();

Fügen Sie die Zeile AopBootstrap::init() in jedes Einstiegsskript ein, zwischen der Erzeugung des Runners und seinem Start: public/index.php, yii (mit seinem ConsoleApplicationRunner und rootPath: __DIR__) und den Bootstrap Ihrer funktionalen Tests. Sie liest die Parameter der Bridge und die Aliase aus der Config des Runners. Der Runner behält diese Config, die Parameter werden also nicht doppelt gebaut.

Der Compile-Step (Kompilierschritt) greift nur für Klassen, die nach dem Start des Kernels geladen werden, und der Yii-Runner lädt Klassen per Autoload, während er den Container baut. Lassen Sie diese Zeile weg, startet die Config-Gruppe bootstrap der Bridge den Kernel zwar trotzdem, aber spät: Klassen, die beim Bau des Containers geladen wurden, werden nicht kompiliert. Im Debug-Modus betrifft das jede Klasse mit einer Array-Definition, die Anwendung würde sich in Entwicklung und Produktion also unterschiedlich verhalten.

<?php
declare(strict_types=1);
namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Psr\Log\LoggerInterface;
final readonly class LoggingAspect implements Aspect
{
public function __construct(private LoggerInterface $logger) {}
#[Before('execution(public App\Service\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
$this->logger->debug('Calling {method}', ['method' => $invocation->getMethod()->getName()]);
}
#[Around('execution(public App\Service\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('charge() took {ms}ms', ['ms' => (hrtime(true) - $start) / 1e6]);
}
}
}

Tragen Sie die Behavior-Klassen in den Parameter aspects ein:

config/common/params.php
'goaop/goaop-yii3-bridge' => [
'aspects' => [
App\Aspect\LoggingAspect::class,
App\Aspect\AuditAspect::class,
],
],

Konstruktorargumente, die sich nicht per Autowiring auflösen lassen, kommen wie bei jedem anderen Service aus einer Container-Definition:

use App\Aspect\AuditAspect;
use Yiisoft\Definitions\Reference;
return [
AuditAspect::class => [
'__construct()' => [
'logger' => Reference::to('auditLogger'),
'level' => $params['app']['auditLevel'],
],
],
];

So wird eine Behavior-Klasse aufgelöst:

  1. Beim Start des Kernels wird nichts per Autoload geladen: Die Klassennamen werden nur syntaktisch geprüft.
  2. Braucht der Compiler die Behaviors einer Klasse, liest er sie per Reflection aus der Klasse. Das Objekt der Behavior-Klasse ist ein nativer Lazy Proxy und noch nicht konstruiert.
  3. Beim ersten Aufruf eines ihrer Behaviors wird der Proxy mit $container->get(AspectClass::class) initialisiert, der geteilten Instanz des Yii-Containers.

Eine Behavior-Klasse, die von einer Datenbankverbindung oder einem HTTP-Client abhängt, erzeugt diese nicht bei Anfragen, die nie eine Methode mit Behavior erreichen. Im Debug-Modus prüft die Bridge, dass jede eingetragene Klasse existiert und Go\Aop\Aspect implementiert.

Ein Paket kann Behavior-Klassen aus seiner eigenen config/params.php beisteuern. Die Gruppe params wird rekursiv zusammengeführt, Listen werden angehängt, und Duplikate werden einmal registriert:

config/params.php
return [
'goaop/goaop-yii3-bridge' => [
'aspects' => [
Vendor\Package\Aspect\CacheAspect::class,
],
],
];

Setzen Sie 'aspectTag' => 'goaop.aspect'. Taggen Sie dann die Definitionen der gemeinsamen Config-Gruppe di ('tags' => ['goaop.aspect']), oder tragen Sie sie in eine gemeinsame Tag-Map di-tags ein (['goaop.aspect' => [LoggingAspect::class]]). Getaggte Services müssen unter ihrem Klassennamen registriert sein.

Die Suche ist wegen ihrer Kosten standardmäßig ausgeschaltet. Die Bridge liest die Tag-Deklarationen aus den Konfigurationsdateien, bevor der Kernel startet; jede Klasse, auf die diese Dateien verweisen (zum Beispiel über eine Klassenkonstante oder einen Enum-Case), wird dann geladen und lässt sich nicht mehr kompilieren. Gelesen werden nur die gemeinsamen Gruppen. Tags von di-web/di-console-Definitionen, di-tags-web/di-tags-console-Maps und Service-Providern werden nicht gesehen.

Die Standardwerte liegen in der Gruppe params der Bridge. Überschreiben Sie sie in config/common/params.php oder pro Umgebung in config/environments/<env>/params.php.

Parameter Standard Zweck
debug null Neu kompilieren, wenn sich Quellen oder Behavior-Klassen ändern. null folgt GOAOP_DEBUG, dann APP_DEBUG. In der Produktion ausgeschaltet lassen.
appDir '@root' Wurzel der Anwendung; nur Dateien darunter werden kompiliert.
cacheDir null Kompilierte Quellen, Proxys und Advisor-Caches. null folgt GOAOP_CACHE_DIR (ein Alias ist erlaubt), dann '@runtime/aop'.
cacheFileMode null Rechte der Cache-Dateien: ein Integer (0770) oder Oktalziffern ('770'). null bedeutet 0770 abzüglich der umask.
features 0 Bitmaske aus Go\Aop\Features-Flags: PREBUILT_CACHE, PARTIAL_REFLECTION, INTERCEPT_INCLUDES.
includePaths ['@src'] Nur diese Verzeichnisse werden kompiliert. Halten Sie die Liste eng.
excludePaths [] Nie kompiliert. Das Cache-Verzeichnis und das Framework sind immer ausgeschlossen.
parsedFilesLimit null Geparste Dateien, die beim Kompilieren im Speicher bleiben, zugleich der Standard von aop:warmup --cached-files. null bedeutet den Standard des Kernels (100).
aspects [] Behavior-Klassen, lazy aus dem Yii-Container aufgelöst.
aspectTag null Optionales Container-Tag, das Behavior-Klassen registriert, z. B. 'goaop.aspect'.

Ein fehlerhafter Parameter scheitert sofort mit einer Meldung, die ihn nennt. Der Kernel steht im Container als Go\Core\AspectKernel (und Go\Yii3\GoAopBridge\Kernel\AspectYii3Kernel) bereit, sein Container als Go\Core\AspectContainer. Sobald der bootstrap-Callback gelaufen ist, delegiert der Container des Kernels unbekannte IDs an den Yii-Container.

Ist yiisoft/yii-console installiert, fügt die Bridge ./yii diese Befehle hinzu:

Befehl Zweck
./yii aop:warmup Kompiliert jede Klasse unterhalb der Include-Pfade in den Cache. --fail-fast, --workers=N, --cache-dir=DIR, --preload[=FILE], --cached-files=N.
./yii aop:opcache Befüllt den OPcache-File-Cache nach aop:warmup mit dem Cache des Frameworks, der Anwendung und ihrer Konfiguration vor.
./yii aop:debug:aspect Listet die Behavior-Klassen mit ihren Matching-Rules (Auswahlregeln) und Advisors (--aspect=... für eine einzelne).
./yii aop:debug:advisor Listet die Advisors oder, was ein Advisor trifft (--advisor=...).
./yii aop:debug:weaving Kompiliert zweimal und meldet Proxys, die sich unterscheiden; das deckt zirkuläre Abhängigkeiten zwischen Behavior-Klassen und kompilierten Klassen auf.

Das sind die eigenen Befehle des Frameworks, registriert im Namespace aop. Sie laufen auf dem Kernel, den die Einstiegszeile initialisiert hat; lassen Sie daher ihr optionales Argument loader weg. Die Worker von --workers=N führen ./yii erneut aus und brauchen die Einstiegszeile. Hat der bootstrap-Fallback den Kernel gestartet, kompiliert der Befehl in seinem eigenen Prozess und weist darauf hin.

Terminal-Fenster
./yii aop:warmup --workers=4

Schalten Sie in Produktion debug aus, und bauen Sie den Cache beim Deployment. --cache-dir=DIR baut den Cache in einem anderen Verzeichnis, während der Kernel weiter sein eigenes verwendet. Die Cache-Dateien sind ortsunabhängig, Sie können das Verzeichnis also an seinen Platz verschieben.

Dockerfile
ENV GOAOP_CACHE_DIR=/app/aop
RUN ./yii aop:warmup --workers=4 --preload

Auf schreibgeschützten Dateisystemen ergänzen Sie Features::PREBUILT_CACHE in features. Die Engine vertraut dem Cache dann vollständig und schreibt nie hinein; bauen Sie ihn daher bei jedem Deployment neu. Eine Klasse unterhalb der Include-Pfade, die der Cache nicht kennt, scheitert mit einer Go\Aop\Exception\WeavingException. Der Prozess von aop:warmup selbst ist davon ausgenommen, damit er diese Klassen in den Cache kompilieren kann.

Mit OPcache schreibt ./yii aop:warmup --preload die Datei _preload.php für opcache.preload in das Cache-Verzeichnis, und ./yii aop:opcache befüllt den File-Cache im finalen Image vor:

Terminal-Fenster
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
./yii aop:opcache --file-cache=/var/cache/opcache
  • Kompiliert werden nur Klassen unter appDir und includePaths. Vendor-Code nicht.
  • Klassen, die vor AopBootstrap::init() geladen werden, etwa App\Environment, lassen sich nicht kompilieren. Ebenso wenig Klassen, die die Konfiguration lädt, während die Einstiegszeile sie liest.
  • Behavior-Klassen müssen selbst nicht kompiliert werden: Schließen Sie ihr Verzeichnis aus, z. B. 'excludePaths' => ['@src/Aspect'].
  • Wenn das Erzeugen einer Behavior-Klasse eines ihrer eigenen Behaviors ausführt, scheitert dieses Behavior mit einer Go\Aop\Exception\AspectCircularReferenceException. Injizieren Sie diese Abhängigkeit lazy (eine Closure oder Psr\Container\ContainerInterface), oder grenzen Sie die Matching-Rule ein.
  • Der Kernel ist prozessglobal. Langlebige Worker (RoadRunner, Swoole, FrankenPHP) initialisieren ihn einmal pro Worker. Setzen Sie Behavior-Klassen, die Zustand pro Anfrage halten, wie jeden anderen geteilten Service zurück.

© 2026 Alexander Lisachenko