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.
Le noyau
Section intitulée « Le noyau »Votre noyau étend Go\Core\AspectKernel et enregistre les behavior classes (des aspects, dans l’API ; voir le tableau des termes) dans configureAop() :
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 :
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'],]);Options du noyau
Section intitulée « Options du noyau »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. |
Drapeaux de fonctionnalités
Section intitulée « Drapeaux de fonctionnalités »Les drapeaux de fonctionnalités sont des constantes de la classe finale Go\Aop\Features. Combinez-les avec | :
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. |
INTERCEPT_INCLUDES
Section intitulée « INTERCEPT_INCLUDES »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.
PREBUILT_CACHE
Section intitulée « PREBUILT_CACHE »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.
PARTIAL_REFLECTION
Section intitulée « PARTIAL_REFLECTION »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 expressionsnew Foo(...)dans les fichiers compilés. Tant qu’une telle règle est enregistrée, chaquenewréé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 :
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.
Règles pour les factories de behavior classes
Section intitulée « Règles pour les factories de behavior classes »- 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 avecaddLazyService(). - 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
AspectCircularReferenceExceptionqui 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.
Classe de conteneur personnalisée
Section intitulée « Classe de conteneur personnalisée »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.
Mode développement et mode production
Section intitulée « Mode développement et mode production »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.
Le répertoire de cache
Section intitulée « Le répertoire de cache »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 aveccache: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 est0770moins 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é.
La console
Section intitulée « La console »vendor/bin/aspect cache:warmup:aop public/index.phpvendor/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. |
cache:warmup:aop
Section intitulée « cache:warmup:aop »rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8La 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-dirpermet à 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.
cache:warmup:opcache
Section intitulée « cache:warmup:opcache »vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.phpCompile 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.
debug:aspect
Section intitulée « debug:aspect »vendor/bin/aspect debug:aspect public/index.phpListe les behavior classes enregistrées et leurs behaviors. Accepte aussi une option --aspect=....
debug:advisor
Section intitulée « debug:advisor »vendor/bin/aspect debug:advisor public/index.phpListe 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.
debug:weaving
Section intitulée « debug:weaving »vendor/bin/aspect debug:weaving public/index.phpPré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.
Les bases du déploiement
Section intitulée « Les bases du déploiement »rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- Videz le répertoire de cache.
- 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. - Exécutez avec
'debug' => falseetFeatures::PREBUILT_CACHE.
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
