Aller au contenu
Documentation · Intégrations

Yii3

Intégration Yii3 avec goaop/goaop-yii3-bridge 1.0 : branchement sur yiisoft/config, behavior classes taggées et ./yii aop:warmup.

Traduit de l’anglais. La page anglaise fait référence. Lire l’original

Le bridge goaop/goaop-yii3-bridge 1.0 se branche sur yiisoft/config. Vos behavior classes (classes de comportement) sont des services ordinaires du conteneur Yii, et le moteur ne résout chacune d’elles qu’au moment où l’un de ses behaviors (comportements) s’exécute pour la première fois.

  • PHP 8.4 ou plus récent
  • Paquets Yii3 : yiisoft/config, yiisoft/di, yiisoft/aliases (comme dans le template d’application)
  • goaop/framework ^4.0 (behaviors déclarés par attributs)
Fenêtre de terminal
composer require goaop/goaop-yii3-bridge

Le plugin yiisoft/config prend en compte la configuration du bridge. Si vous l’avez installé avec le plugin désactivé, lancez composer yii-config-rebuild.

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

Ajoutez la ligne AopBootstrap::init() à chaque script d’entrée, entre la création du runner et son exécution : public/index.php, yii (avec son ConsoleApplicationRunner et rootPath: __DIR__), et le bootstrap de vos tests fonctionnels. Elle lit les paramètres du bridge et les alias depuis la configuration du runner. Le runner conserve cette configuration : les paramètres ne sont donc pas construits deux fois.

La compile step (étape de compilation) ne s’applique qu’aux classes chargées après le démarrage du noyau (kernel), et le runner Yii autocharge des classes pendant qu’il construit le conteneur. Si vous omettez cette ligne, le groupe de configuration bootstrap du bridge démarre quand même le noyau, mais tardivement : les classes chargées pendant la construction du conteneur ne sont pas compilées. En mode debug, cela inclut toutes les classes dotées d’une définition sous forme de tableau : l’application se comporterait alors différemment en développement et en production.

<?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]);
}
}
}

Listez les behavior classes dans le paramètre aspects :

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

Les arguments de constructeur qui ne peuvent pas être autowirés proviennent d’une définition du conteneur, comme pour n’importe quel autre service :

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

Comment une behavior class est résolue :

  1. Rien n’est autochargé au démarrage du noyau : les noms de classes sont seulement validés syntaxiquement.
  2. Lorsque le compilateur a besoin des behaviors d’une classe, il les lit dans la classe par réflexion. L’objet de la behavior class est un proxy paresseux natif et n’est pas encore construit.
  3. Au premier appel de l’un de ses behaviors, le proxy est initialisé avec $container->get(AspectClass::class), l’instance partagée du conteneur Yii.

Une behavior class qui dépend d’une connexion à la base de données ou d’un client HTTP ne les crée pas lors des requêtes qui n’atteignent jamais une méthode dotée d’un behavior. En mode debug, le bridge vérifie que chaque classe listée existe et implémente Go\Aop\Aspect.

Un paquet peut apporter des behavior classes depuis son propre config/params.php. Le groupe params est fusionné récursivement, les listes sont concaténées, et les doublons ne sont enregistrés qu’une fois :

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

Définissez 'aspectTag' => 'goaop.aspect'. Ajoutez ensuite le tag aux définitions du groupe de configuration commun di ('tags' => ['goaop.aspect']), ou listez-les dans une table de tags commune di-tags (['goaop.aspect' => [LoggingAspect::class]]). Les services taggés doivent être enregistrés sous leur nom de classe.

Cette recherche est désactivée par défaut en raison de son coût. Le bridge lit les déclarations de tags dans les fichiers de configuration avant le démarrage du noyau : chaque classe que ces fichiers référencent (par une constante de classe ou un cas d’enum, par exemple) est donc chargée à ce moment-là et ne peut plus être compilée. Seuls les groupes communs sont lus. Les tags des définitions di-web/di-console, les tables di-tags-web/di-tags-console et les service providers ne sont pas vus.

Les valeurs par défaut se trouvent dans le groupe params du bridge. Surchargez-les dans config/common/params.php, ou par environnement dans config/environments/<env>/params.php.

Paramètre Valeur par défaut Rôle
debug null Recompiler quand les sources ou les behavior classes changent. null suit GOAOP_DEBUG, puis APP_DEBUG. À désactiver en production.
appDir '@root' Racine de l’application ; seuls les fichiers situés en dessous sont compilés.
cacheDir null Sources compilées, proxies et caches des advisors. null suit GOAOP_CACHE_DIR (un alias est accepté), puis '@runtime/aop'.
cacheFileMode null Droits des fichiers de cache : un entier (0770) ou des chiffres octaux ('770'). null signifie 0770 moins l’umask.
features 0 Masque de bits des drapeaux Go\Aop\Features : PREBUILT_CACHE, PARTIAL_REFLECTION, INTERCEPT_INCLUDES.
includePaths ['@src'] Seuls ces répertoires sont compilés. Gardez la liste restreinte.
excludePaths [] Jamais compilés. Le répertoire de cache et le framework sont toujours exclus.
parsedFilesLimit null Fichiers analysés gardés en mémoire pendant la compilation, également la valeur par défaut de aop:warmup --cached-files. null signifie la valeur par défaut du noyau (100).
aspects [] Behavior classes, résolues en différé depuis le conteneur Yii.
aspectTag null Tag de conteneur optionnel qui enregistre les behavior classes, par ex. 'goaop.aspect'.

Un paramètre mal formé échoue immédiatement avec un message qui le nomme. Le noyau est disponible dans le conteneur sous Go\Core\AspectKernel (et Go\Yii3\GoAopBridge\Kernel\AspectYii3Kernel), son conteneur sous Go\Core\AspectContainer. Une fois le callback bootstrap exécuté, le conteneur du noyau délègue les identifiants inconnus au conteneur Yii.

Avec yiisoft/yii-console installé, le bridge ajoute ces commandes à ./yii :

Commande Rôle
./yii aop:warmup Compile dans le cache chaque classe sous les chemins d’inclusion. --fail-fast, --workers=N, --cache-dir=DIR, --preload[=FILE], --cached-files=N.
./yii aop:opcache Amorce le file cache d’OPcache avec le cache du framework, l’application et sa configuration, après aop:warmup.
./yii aop:debug:aspect Liste les behavior classes avec leurs matching rules (règles de correspondance) et leurs advisors (--aspect=... pour une seule).
./yii aop:debug:advisor Liste les advisors, ou ce qu’un advisor sélectionne (--advisor=...).
./yii aop:debug:weaving Compile deux fois et signale les proxies qui diffèrent, ce qui révèle les dépendances circulaires entre behavior classes et classes compilées.

Ce sont les commandes propres au framework, enregistrées dans l’espace de noms aop. Elles s’exécutent sur le noyau qu’a initialisé la ligne d’entrée : omettez donc leur argument facultatif loader. Les workers de --workers=N relancent ./yii et ont besoin de la ligne d’entrée. Lorsque c’est le repli bootstrap qui a démarré le noyau, la commande compile dans son propre processus et l’indique.

Fenêtre de terminal
./yii aop:warmup --workers=4

En production, désactivez debug et construisez le cache au déploiement. --cache-dir=DIR construit le cache dans un autre répertoire pendant que le noyau continue d’utiliser le sien. Les fichiers de cache sont indépendants de leur emplacement : vous pouvez donc mettre le répertoire en place par simple déplacement.

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

Sur les systèmes de fichiers en lecture seule, ajoutez Features::PREBUILT_CACHE à features. Le moteur fait alors entièrement confiance au cache et n’y écrit jamais : reconstruisez-le donc à chaque déploiement. Une classe sous les chemins d’inclusion que le cache ne connaît pas échoue avec une Go\Aop\Exception\WeavingException. Le processus aop:warmup lui-même en est exempté, pour pouvoir compiler ces classes dans le cache.

Avec OPcache, ./yii aop:warmup --preload écrit _preload.php dans le répertoire de cache pour opcache.preload, et ./yii aop:opcache amorce le file cache dans l’image finale :

Fenêtre de terminal
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
  • Seules les classes sous appDir et includePaths sont compilées. Le code vendor ne l’est pas.
  • Les classes chargées avant AopBootstrap::init(), comme App\Environment, ne peuvent pas être compilées. Pas plus que les classes que la configuration charge pendant que la ligne d’entrée la lit.
  • Les behavior classes elles-mêmes n’ont pas besoin d’être compilées : excluez leur répertoire, par ex. 'excludePaths' => ['@src/Aspect'].
  • Lorsque la création d’une behavior class exécute l’un de ses propres behaviors, ce behavior échoue avec une Go\Aop\Exception\AspectCircularReferenceException. Injectez cette dépendance en différé (une closure ou Psr\Container\ContainerInterface), ou restreignez la matching rule.
  • Le noyau est global au processus. Les workers de longue durée (RoadRunner, Swoole, FrankenPHP) l’initialisent une fois par worker. Réinitialisez les behavior classes qui conservent un état par requête, comme n’importe quel autre service partagé.

© 2026 Alexander Lisachenko