Symfony
Intégration Symfony avec goaop/goaop-symfony-bundle 4.0 : behavior classes autoconfigurées, panneau dans le web profiler et préchauffage du cache.
Traduit de l’anglais. La page anglaise fait référence. Lire l’original
Le bundle goaop/goaop-symfony-bundle 4.0 attache des behaviors (comportements) à vos services au moment où ils sont chargés. Vous n’avez besoin ni de classes de base ni de décorateurs.
namespace App\Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect{ public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')] public function measure(MethodInvocation $invocation): mixed { $start = hrtime(true); try { return $invocation->proceed(); } finally { $this->logger->info('{method} took {ms} ms', [ 'method' => (string) $invocation, 'ms' => (hrtime(true) - $start) / 1e6, ]); } }}C’est toute l’intégration. La classe implémente Go\Aop\Aspect : l’autoconfiguration l’enregistre donc comme behavior class (classe de comportement), et l’autowiring lui fournit son logger. Dès la requête suivante, chaque méthode publique de chaque classe sous App\Service est chronométrée.
Prérequis
Section intitulée « Prérequis »- PHP 8.4 ou plus récent
- Symfony 7.4 ou 8.x
goaop/framework^4.0 (behaviors déclarés par attributs)
Installer et activer le bundle
Section intitulée « Installer et activer le bundle »composer require goaop/goaop-symfony-bundleEnregistrez le bundle comme première entrée de config/bundles.php :
return [ Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true], Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true], // ...];La compile step (étape de compilation) ne s’applique qu’aux classes chargées après l’initialisation du noyau (kernel), et les bundles démarrent dans l’ordre de leur enregistrement. Le bundle l’impose : s’il n’est pas en premier, la construction du conteneur échoue avec un message explicite.
Configuration
Section intitulée « Configuration »Le fichier de configuration est facultatif. Avec les valeurs par défaut ci-dessous, le bundle compile le répertoire src/ dans le mode du noyau et active le cache préconstruit en production :
go_aop: include_paths: ['%kernel.project_dir%/src']
when@prod: go_aop: features: [PREBUILT_CACHE]bin/console config:dump-reference go_aop affiche la référence complète. Toutes les options, avec leurs valeurs par défaut :
go_aop: # Development mode: changed sources and behavior classes are compiled again on the next request, # breakpoints work in the original files. Keep it off in production. debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it. app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir% # or %kernel.build_dir% so that cache:clear and cache:warmup manage it. cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer. # Defaults to 0770 minus the umask. cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed. include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the # framework itself are always excluded). exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each). parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant: # PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime # INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code) # PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not # locate, with their own members features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize # the transformation pipeline. kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear. cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered. doctrine: ~Les variables d’environnement fonctionnent comme partout dans Symfony, par exemple debug: '%env(bool:GOAOP_DEBUG)%'. Les matching rules (règles de correspondance) de fonctions et initialization() n’ont besoin d’aucun drapeau de fonctionnalité : elles activent elles-mêmes leur machinerie.
Enregistrer les behavior classes
Section intitulée « Enregistrer les behavior classes »Une behavior class est un service autowiré ordinaire. L’autoconfiguration enregistre chaque service qui implémente Go\Aop\Aspect. Sans autoconfiguration, ajoutez au service le tag goaop.aspect :
services: Acme\Audit\AuditAspect: tags: [goaop.aspect]Une behavior class est un singleton : l’enregistrer comme deux services provoque une erreur de compilation du conteneur.
Le compilateur n’a besoin que des behavior classes. Le conteneur Symfony instancie une behavior class lorsque l’un de ses behaviors s’exécute pour la première fois, jamais pendant la compile step ni pendant le préchauffage du cache. Le conteneur du noyau (AspectContainer) délègue aussi au conteneur Symfony : $aspectContainer->get(LoggerInterface::class) fonctionne donc. Go\Core\AspectKernel et Go\Core\AspectContainer sont des services autowirables, et goaop.aspect_kernel est public.
Vérifiez ce qu’une behavior class sélectionne avant de compter dessus :
bin/console debug:aspect # behavior classes with their rules and behaviorsbin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matchesEn mode debug, les classes sous les chemins d’inclusion sont compilées à leur premier chargement, puis recompilées dès que leur source ou une behavior class change.
Panneau du web profiler
Section intitulée « Panneau du web profiler »Avec symfony/web-profiler-bundle installé, la barre d’outils affiche le nombre de behavior classes. Le panneau Go! AOP liste :
- les behavior classes avec leurs advisors, leurs attributs de behavior et leurs matching rules ;
- les classes compilées chargées pendant la requête, avec leurs fichiers de proxy ;
- les classes sous les chemins d’inclusion qui ont été chargées avant l’initialisation du noyau (le panneau passe au jaune) ;
- la configuration effective du noyau.
La troisième liste sert de diagnostic pour un bundle qui démarre avant GoAopBundle, ainsi que pour l’unique requête qui a reconstruit le conteneur. Cette requête doit charger les classes de services avant le démarrage du bundle : elle les exécute donc une fois sans leurs behaviors. La requête suivante s’exécute entièrement compilée. Les déploiements ne sont pas concernés, car cache:clear et cache:warmup construisent ensemble le conteneur et le cache du framework.
Le bundle désactive aussi l’option .container.dumper.inline_class_loader de Symfony, sauf si votre configuration la définit. Cette option inclut directement les fichiers des services, ce qui contourne le chargeur de classes et donc la compile step.
Préchauffage du cache
Section intitulée « Préchauffage du cache »composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts# or explicitlybin/console cache:clearbin/console cache:warmupcache:clear et cache:warmup compilent toute l’application via un cache warmer. cache:clear construit le nouveau cache à côté de celui en service, puis le renomme. Le warmer construit le cache du framework dans ce nouveau répertoire, à partir de zéro : vos étapes de déploiement habituelles n’ont donc pas à changer. Le préchauffage échoue lorsqu’un fichier ne peut pas être compilé, si bien qu’un déploiement s’arrête au lieu de livrer un cache incomplet. Lancez cache:warmup:aop --fail-fast -vvv pour voir le fichier et l’erreur.
Les commandes du framework sont enregistrées dans la console de votre application. Elles travaillent sur le noyau en cours d’exécution : vous omettez donc l’argument loader de vendor/bin/aspect.
| Commande | Rôle |
|---|---|
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] |
Compile dans le cache chaque fichier sous les chemins d’inclusion. Échoue lorsqu’un fichier ne peut pas être compilé. --preload écrit aussi le script opcache.preload du cache. |
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] |
Amorce le file cache d’OPcache (opcache.file_cache) avec le cache du framework et l’application. À lancer dans l’image finale. |
debug:aspect [--aspect=FQCN] |
Liste les behavior classes avec leurs matching rules et leurs advisors. |
debug:advisor [--advisor=ID] |
Liste les advisors ; avec --advisor, ce que cet advisor sélectionne. |
debug:weaving [-v] |
Compile l’application deux fois et signale les proxies qui diffèrent, ce qui révèle une behavior class non déterministe. |
Ici, cache:warmup:aop --workers=N compile dans un seul processus : ses processus workers démarreraient le noyau avec un fichier loader, et la console de l’application n’en a pas.
Réglages de production
Section intitulée « Réglages de production »when@prod: go_aop: features: [PREBUILT_CACHE]Avec PREBUILT_CACHE, l’exécution saute toutes les vérifications du système de fichiers liées au cache, et ne compile ni n’écrit jamais dans le répertoire de cache. Une classe sous les chemins d’inclusion que le cache ne connaît pas échoue avec une WeavingException (« … is missing from the prebuilt AOP cache … »). Reconstruisez le cache à chaque déploiement. C’est le réglage recommandé en production, et il permet les systèmes de fichiers en lecture seule et les images immuables.
Si votre kernel.build_dir diffère de kernel.cache_dir, ancrez le cache du framework sur le répertoire que vous construisez au déploiement : cache_dir: '%kernel.build_dir%/aop'.
Pour le préchargement d’OPcache, chargez le script de préchargement du cache du framework avant le fichier de préchargement du conteneur :
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) { require $aop;}if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) { require $container;}En mode production, le cache warmer écrit _preload.php dans le répertoire de cache du framework. Adaptez son chemin lorsque cache_dir n’est pas %kernel.cache_dir%/aop. Ne démarrez pas le noyau dans config/preload.php : cela échoue avec « Cannot redeclare class ». Pour en savoir plus sur les builds de production : Production et performances.
Doctrine ORM dans Symfony
Section intitulée « Doctrine ORM dans Symfony »Lorsque DoctrineBundle est enregistré, ou lorsque vous définissez doctrine: true, le bundle :
- remplace le parcours de répertoires de chaque driver d’attributs de l’ORM par
Go\Bridge\Doctrine\WovenEntityClassLocator, qui charge les entités via le chargeur de classes, si bien qu’elles conservent leurs behaviors ; - enregistre
Go\Bridge\Doctrine\MetadataLoadInterceptorcomme listenerloadClassMetadata, qui signale, au chargement des métadonnées, une propriété d’entité interceptée lorsque les objets paresseux natifs (native lazy objects) sont désactivés.
Les entités doivent se trouver sous un chemin d’inclusion pour être compilées. Leurs behaviors s’appliquent alors, que ce soit votre code qui les crée ou l’ORM qui les hydrate. La page Doctrine ORM explique ces deux classes.
Dépannage
Section intitulée « Dépannage »-
Un behavior ne s’applique pas. Lancez d’abord
debug:advisor --advisor=...: il liste ce qu’une matching rule sélectionne. Vérifiez ensuite que la classe se trouve sous un chemin d’inclusion et qu’elle n’est pas chargée avant le démarrage du bundle (panneau du profiler, classes loaded before weaving). Le code vendor n’est compilé que si son répertoire est un chemin d’inclusion. -
« Class … is missing from the prebuilt AOP cache ». Le déploiement a livré du code pour lequel le cache n’a pas été construit. Lancez
bin/console cache:clear(oucache:warmup) une fois le code en place. -
« Circular reference detected for the aspect … ». La création de l’une des dépendances de la behavior class exécute un behavior de cette même classe. Injectez la dépendance en différé, ou restreignez la matching rule :
public function __construct(#[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator) {} -
« Class … was not found by locator ». Une classe sous les chemins d’inclusion étend du code que Composer ne sait pas localiser, comme une classe de base générée. Laissez Composer la localiser, activez
PARTIAL_REFLECTION, ou excluez les classes dépendantes avecexclude_paths. -
Gestionnaires d’exceptions. Excluez via
exclude_pathsles classes qui doivent se charger quand tout le reste a échoué (gestionnaires d’erreurs, le noyau).
© 2026 Alexander Lisachenko
