Aller au contenu
Documentation

Configuration et CLI

Configurez le noyau, choisissez les drapeaux de fonctionnalités, fournissez aux behavior classes leurs dépendances depuis le conteneur de votre application et utilisez la console.

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

Tout ce que le framework doit savoir de votre application passe par un seul appel : init() sur votre noyau (kernel). Cette page liste toutes les options qu’accepte le noyau, les drapeaux de fonctionnalités, la manière dont les behavior classes (classes de comportement) obtiennent leurs dépendances depuis le conteneur de votre application, et la console vendor/bin/aspect qui sert à construire et à inspecter le cache.

Votre noyau étend Go\Core\AspectKernel et enregistre les behavior classes (des aspects, dans l’API ; voir le tableau des termes) dans configureAop() :

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

Vous l’initialisez une seule fois, généralement dans le contrôleur frontal, juste après l’autoloader de Composer :

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

Seules les options ci-dessous sont acceptées. Une clé inconnue, un containerClass inconnu ou un bit de fonctionnalité inconnu lève Go\Aop\Exception\InvalidConfigurationException : une faute de frappe échoue dès le démarrage au lieu d’être ignorée.

Option Type Défaut Rôle
cacheDir string aucun, obligatoire Répertoire des sources compilées, des proxies, des caches d’advisors et de la class map.
appDir string le répertoire qui contient vendor/ Racine de l’application. Les chemins du cache reproduisent les chemins des sources relativement à elle, et seuls les fichiers situés en dessous sont compilés.
debug bool false Mode développement : toute modification du fichier du noyau ou des fichiers de behavior classes invalide le cache, et chaque classe et chaque include passe par le stream filter de compilation du framework. Avec false, les classes compilées sont chargées depuis le cache via la class map de Composer. Utilisez false en production.
includePaths string[] [] (tout ce qui se trouve sous appDir) Les répertoires compilés. Gardez cette liste restreinte : compiler le code des dépendances (vendor) est lent et rarement utile.
excludePaths string[] [] Les répertoires jamais compilés. Le répertoire de cache, le framework lui-même et ses dépendances d’exécution (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) sont toujours exclus.
features int 0 Masque de bits de drapeaux Go\Aop\Features, voir la section suivante.
cacheFileMode int 0770 moins l’umask Permissions des fichiers de cache. Doit être compris entre 0600 et 0777 et donner au propriétaire les droits de lecture et d’écriture ; les répertoires reçoivent les bits de traversée correspondants.
containerClass class-string Go\Core\Container Implémentation du conteneur du noyau. Doit implémenter Go\Core\AspectContainer (un ContainerInterface PSR-11).
parsedFilesLimit int 100 Nombre de fichiers sources analysés (arbres syntaxiques, environ 0,2 Mo chacun) que goaop/parser-reflection garde en mémoire pendant la compilation. Doit être un entier positif : une valeur plus élevée réanalyse moins, une valeur plus faible consomme moins de mémoire. Remplace une limite fixée avec ReflectionEngine::setMaximumCachedFiles() avant init(), et sert de valeur par défaut à cache:warmup:aop --cached-files.

Les drapeaux de fonctionnalités sont des constantes de la classe finale Go\Aop\Features. Combinez-les avec | :

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 combine tous les drapeaux. AspectKernel::hasFeature() indique si un drapeau est activé et lève une exception pour un drapeau inconnu.

Drapeau À utiliser quand
INTERCEPT_INCLUDES Votre application charge du code avec include/require plutôt qu’avec Composer.
PREBUILT_CACHE Vous construisez le cache au déploiement et voulez que les requêtes lui fassent entièrement confiance. Le réglage de production.
PARTIAL_REFLECTION Une classe que vous voulez compiler étend ou implémente quelque chose que le framework ne parvient pas à localiser.

Fait passer les include et require des fichiers compilés par le compilateur. À utiliser pour du code legacy qui n’est pas chargé par Composer.

Fait entièrement confiance au cache construit au déploiement. Le noyau saute les sondages du répertoire de cache et de ses droits d’écriture, les comparaisons de filemtime des sources, les vérifications des ressources suivies et celles de la fraîcheur du cache des advisors. Une requête ne compile jamais et n’écrit jamais dans le répertoire de cache : elle fonctionne donc sur des systèmes de fichiers en lecture seule.

Le revers de la médaille : le cache doit être complet. Les fichiers que le compilateur ne prend jamais en charge (hors des chemins d’inclusion, exclus, ou qui ne sont pas des fichiers .php, par exemple un template inclus) sont chargés tels quels. Tout le reste, sous les chemins d’inclusion, doit avoir une entrée dans le cache.

cache:warmup:aop lui-même ne fait pas confiance au cache qu’il construit. Lancé sur un répertoire existant, il recompile chaque fichier dont la source a changé (taille ou date de modification). Son fichier de chargement (loader) peut charger, avant le début de la construction, des classes que le cache ne connaît pas encore : elles y sont chargées sans compilation, puis compilées par la construction.

Compile une classe dont la classe parente, une interface ou un trait est introuvable : un élément déclaré par du code généré à l’exécution, par un class_alias() ou dans un fichier hors de l’autoloader de Composer. La classe est sélectionnée et compilée avec ses propres méthodes et propriétés, ainsi que celles de ses ancêtres disponibles. Les membres hérités d’un ancêtre manquant ne sont pas interceptés.

Sans ce drapeau, une telle classe ne se compile pas. Activez-le quand vous rencontrez cet échec.

Les règles de fonctions et d’initialisation n’ont besoin d’aucun drapeau

Section intitulée « Les règles de fonctions et d’initialisation n’ont besoin d’aucun drapeau »

Le framework active le mécanisme nécessaire à ces matching rules (règles de correspondance) d’après les behavior classes enregistrées, y compris celles enregistrées en différé. Vous n’avez rien à mettre dans features :

  • Une règle execution(Namespace\function(*)) ajoute des proxies de fonctions aux espaces de noms correspondants.
  • Une règle initialization(...) active la réécriture des expressions new Foo(...) dans les fichiers compilés. Tant qu’une telle règle est enregistrée, chaque new réécrit passe par l’intercepteur : limitez donc ces règles au code qui en a besoin.

La syntaxe des matching rules est décrite dans Behaviors et matching rules.

Behavior classes depuis le conteneur de l’application

Section intitulée « Behavior classes depuis le conteneur de l’application »

Le conteneur du noyau est un conteneur PSR-11 (Go\Core\AspectContainer étend Psr\Container\ContainerInterface). Il peut déléguer au conteneur de votre application : Symfony, Laravel, PHP-DI ou n’importe quel autre conteneur PSR-11. get(), getService() et has() se replient sur le délégué pour les identifiants qui ne sont pas enregistrés dans le conteneur du noyau.

Le noyau est initialisé avant que l’application ne construise son conteneur. Vous enregistrez donc les behavior classes comme d’habitude et les laissez résoudre leurs dépendances de façon paresseuse :

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'));
}

Une fois le conteneur de l’application disponible, par exemple juste après le démarrage du noyau de votre framework, rattachez-le :

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

La compile step (étape de compilation) et le préchauffage du cache n’ont besoin que de la behavior class elle-même. Ils s’exécutent avant setDelegate(), y compris dans vendor/bin/aspect, et n’en créent jamais d’instance. La factory s’exécute la première fois que l’un de ses behaviors (comportements) s’exécute ; une dépendance encore manquante à ce moment-là lève ServiceNotFoundException.

Les bridges Symfony, Laravel et Yii 3 sont décrits dans Intégrations.

  • Une factory ne demande jamais son propre identifiant au conteneur du noyau. Cet identifiant désigne la behavior class en cours de construction. Prenez l’instance dans le conteneur de l’application, sous l’identifiant qu’elle y porte, ou construisez-la à partir de ses dépendances.
  • Les behavior classes ne sont jamais découvertes dans le délégué. Un conteneur PSR-11 ne peut pas être inspecté : il n’existe aucun moyen standard d’y chercher des services par interface ou par tag. Chaque behavior class est enregistrée dans configureAop(). Un bridge propre à un framework peut collecter des services par tag ou par interface dans son propre conteneur et les enregistrer avec addLazyService().
  • La compile step ne crée jamais d’instance de behavior class. Elle lit la behavior class, et le code généré désigne chaque behavior par le nom de sa classe et de sa méthode. Chaque behavior class, y compris une classe sans propriétés d’instance (que PHP ne peut pas rendre paresseuse), est créée par sa factory la première fois que l’un de ses behaviors s’exécute, une fois le conteneur de l’application rattaché.
  • Créer une behavior class ne doit déclencher aucun de ses propres behaviors. Si la behavior class dépend d’un service dont l’un de ses behaviors intercepte la construction (le constructeur du service, ou une méthode que ce constructeur appelle), ce behavior s’exécuterait sur une instance qui n’existe pas encore. L’intercepteur signale ce cas par une AspectCircularReferenceException qui nomme la behavior class, l’appel intercepté et les appels qui mènent de la création au behavior. Injectez la dépendance de façon paresseuse (un service paresseux, une closure ou un service locator), ou restreignez la matching rule pour que la behavior class n’intercepte pas la création de ses propres dépendances.

Pour remplacer le conteneur du noyau, passez votre classe dans containerClass. Elle doit implémenter Go\Core\AspectContainer, c’est-à-dire les méthodes PSR-11 get() et has(), plus setDelegate(). Un identifiant inconnu lève ServiceNotFoundException, qui implémente Psr\Container\NotFoundExceptionInterface.

L’option debug bascule entre deux modes. Vos behavior classes et vos matching rules sont les mêmes dans les deux.

'debug' => true 'debug' => false
Chargement des classes Chaque classe et chaque include passe par le stream filter de compilation. Les classes compilées viennent du cache via la class map de Composer.
Source, behavior class ou fichier du noyau modifié Recompilé à la requête suivante. Le cache est servi tel quel.
Reconstruction du cache Inutile. À chaque déploiement, avec cache:warmup:aop.
Usage Développement local. Production. Ajoutez Features::PREBUILT_CACHE.

En développement, il n’y a pas d’étape de build : modifiez une classe ou un behavior, rechargez, et le framework recompile ce qui a changé. Les points d’arrêt fonctionnent dans votre code d’origine.

En production, le framework transmet la class map du cache à Composer, et le parseur et les transformateurs ne sont pas chargés sur les requêtes à chaud. Avec PREBUILT_CACHE en plus, une requête saute aussi toutes les vérifications des fichiers sources et de la fraîcheur du cache. Pour aller plus loin dans le réglage (OPcache, préchargement, conteneurs), voir Production et performances.

cacheDir est la seule option obligatoire. Le répertoire contient :

  • les sources compilées : le corps de chaque classe d’origine sous forme de trait <Class>OriginalTrait, au chemin relatif de son fichier source ;
  • les proxies, à côté des sources compilées, sous le nom de la classe d’origine ;
  • les caches d’advisors de vos behavior classes, sous forme de fichiers PHP ordinaires à côté des sources compilées ;
  • les métadonnées, dont _include.cache, la class map transmise à Composer ;
  • _preload.php, quand vous construisez le cache avec cache:warmup:aop --preload.

À savoir :

  • Il reproduit appDir. Les chemins du cache sont relatifs à la racine de l’application, et les chemins stockés dans les métadonnées sont relatifs à __DIR__ : le cache reste donc valide quand le répertoire de l’application est déplacé.
  • Il n’est jamais compilé. Le répertoire de cache est toujours exclu, quel que soit le contenu d’excludePaths.
  • Les permissions viennent de cacheFileMode. La valeur par défaut est 0770 moins l’umask. Construisez le cache avec l’utilisateur qui sert les requêtes, ou pour lui.
  • Supprimez-le quand vous migrez depuis la 3.x. Aucun fichier de cache 3.x n’est réutilisé, et avec PREBUILT_CACHE, un cache construit par une autre version du framework est rejeté.
Fenêtre de terminal
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/bin/aspect nécessite symfony/console (^7.4 || ^8.0). Installez-le avec Composer si votre application ne l’a pas encore.

Chaque commande prend le chemin du fichier qui initialise votre noyau, généralement le contrôleur frontal ou un fichier de bootstrap. Ce fichier est exécuté : la commande voit donc le noyau avec les mêmes options que votre application. Au sein d’une application qui a déjà initialisé son noyau (la console d’une intégration de framework, où les commandes sont enregistrées comme services), vous omettez l’argument : les commandes utilisent le noyau du processus.

Chaque commande renvoie Command::SUCCESS ou Command::FAILURE. Vérifiez le code de sortie dans vos scripts.

Commande Rôle
cache:warmup:aop Compile dans le cache chaque fichier situé sous les chemins d’inclusion.
cache:warmup:opcache Amorce opcache.file_cache avec le cache du framework et ce que charge une requête.
debug:aspect Liste les behavior classes enregistrées et leurs behaviors.
debug:advisor Liste les advisors (chaque behavior avec sa matching rule), ou les appels interceptés que sélectionne un advisor.
debug:weaving Préchauffe le cache deux fois et signale les proxies générés différemment.
Fenêtre de terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

La commande compile chaque fichier situé sous includePaths (moins excludePaths) et écrit les fichiers compilés, les proxies, les caches d’advisors et les métadonnées. Elle affiche une barre de progression. Elle signale sur stderr chaque fichier qui ne peut pas être compilé et se termine avec un code non nul : un script de déploiement ou un docker build s’arrête donc là au lieu de livrer un cache incomplet.

Option Défaut Rôle
--workers=N 1 (compile dans le processus de la commande) Compile dans N processus workers en parallèle. Indiquez le nombre de CPU.
--cached-files=N l’option de noyau parsedFilesLimit, 100 Nombre de fichiers analysés que chaque processus garde en mémoire.
--fail-fast désactivé S’arrête au premier fichier qui ne peut pas être compilé.
--cache-dir=DIR le cacheDir du noyau Construit le cache dans un autre répertoire, à partir de zéro, pendant que le noyau et les workers continuent d’utiliser le leur.
--preload[=FILE] désactivé Écrit aussi le script opcache.preload du cache : _preload.php dans le répertoire de cache, ou FILE.
-v désactivé Affiche chaque fichier au lieu de la seule barre de progression.

Remarques sur les options :

  • --cache-dir permet à un déploiement de préparer le cache de la prochaine version à côté de celui en service, puis de basculer de façon atomique, par exemple en échangeant un lien symbolique. Un cache construit ainsi est complet et indépendant de son emplacement, y compris quand un noyau de production le construit alors que son propre cache est chaud : le compilateur lit toujours les sources d’origine, jamais les fichiers compilés que sert Composer.
  • --preload, sous sa forme nue, doit venir après l’argument du loader, sinon il prend le loader comme valeur. Le script lie au démarrage de PHP chaque classe compilée et chaque classe non transformée connue du cache ; les classes qui ont un behavior sur l’initialisation statique sont laissées à l’autoloader. Il ne contient aucun chemin absolu et liste précisément les classes de ce cache : vous le reconstruisez donc avec le cache. La mise en place du préchargement est décrite dans Production et performances.
  • Sur un répertoire existant, la commande recompile chaque fichier dont la source a changé (taille ou date de modification) et conserve les autres, y compris avec PREBUILT_CACHE. Partez d’un répertoire vide si vous voulez que le cache contienne exactement la version en cours.
Fenêtre de terminal
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

Compile dans opcache.file_cache ce que charge une requête de production : le cache du framework, la class map et les fichiers chargés automatiquement par Composer, les sources non transformées, le loader et les points d’entrée. Un nouveau processus maître PHP-FPM ou un processus CLI lit alors les scripts compilés sur le disque au lieu de les compiler.

Option Rôle
--file-cache=DIR Le répertoire opcache.file_cache. Il doit correspondre à celui qui est configuré.
--entry=FILE Un point d’entrée à compiler. Répétez l’option pour plusieurs fichiers.

Les scripts compilés ne sont écrits sur le disque que par un processus lancé avec -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR. Si la commande s’exécute sans ces options, elle affiche la commande exacte à lancer.

Le file cache dépend du build de PHP et des chemins absolus des fichiers. Lancez la commande dans l’image finale, après cache:warmup:aop, avec le binaire PHP qui sert les requêtes. Le cache du framework, le loader et les points d’entrée doivent compiler, sinon la commande échoue ; les fichiers de la class map de Composer qui ne compilent pas sont listés et ignorés.

Fenêtre de terminal
vendor/bin/aspect debug:aspect public/index.php

Liste les behavior classes enregistrées et leurs behaviors. Accepte aussi une option --aspect=....

Fenêtre de terminal
vendor/bin/aspect debug:advisor public/index.php

Liste les advisors. Avec --advisor=..., affiche les appels interceptés que sélectionne cet advisor : vous savez ainsi si votre matching rule sélectionne bien les méthodes attendues.

Fenêtre de terminal
vendor/bin/aspect debug:weaving public/index.php

Préchauffe le cache deux fois et signale les proxies générés différemment entre les deux passes. Une différence trahit une behavior class non déterministe.

Fenêtre de terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. Videz le répertoire de cache.
  2. Préchauffez le cache avec cache:warmup:aop. La commande échoue lorsqu’un fichier ne peut pas être compilé : le déploiement s’arrête donc au lieu de livrer un cache incomplet. Les gros projets compilent plus vite en parallèle avec --workers.
  3. Exécutez avec 'debug' => false et 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,
]);

Reconstruisez le cache chaque fois que le code, les behavior classes, les options du noyau ou composer.lock changent. En pratique, à chaque déploiement. Le mode développement ne nécessite aucune reconstruction.

Le réglage d’OPcache, le préchargement, les options de l’autoloader de Composer et la construction du cache dans une image Docker sont décrits dans Production et performances. La migration depuis la 3.x, y compris le changement de format du cache, est décrite dans Limitations et migration.

© 2026 Alexander Lisachenko