Aller au contenu
Documentation

Premiers pas

Installez le framework avec Composer, créez un noyau, écrivez votre premier behavior et regardez-le s’exécuter autour de votre code.

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

Un behavior (comportement) comme la journalisation, la mise en cache, un contrôle de sécurité ou une transaction s’écrit une seule fois : le framework l’attache ensuite comme middleware dynamique à chaque méthode que vous sélectionnez. Dans le code, les behaviors vivent dans une behavior class (classe de comportement, un aspect dans l’API) : chaque behavior est une méthode dont l’attribut indique quand elle s’exécute et porte une matching rule (règle de correspondance) qui indique où. Vos classes ne gardent que leur logique métier. Le tableau des termes fait correspondre les noms de l’API aux mots qu’emploie cette documentation.

  • PHP 8.4 ou plus récent. Fonctionne avec toutes les versions modernes de PHP.
  • Aucune extension PECL ou PIE. C’est du PHP pur : ni php-aop, ni runkit, ni uopz, et pas d’eval(). Le framework utilise l’extension tokenizer.
  • Composer. Le framework et ses dépendances s’installent comme des paquets Composer ordinaires.

La mise en route tient en cinq étapes :

  1. Installer le framework avec Composer.
  2. Créer le noyau (kernel) de l’application.
  3. Initialiser le noyau dans le contrôleur frontal.
  4. Écrire une behavior class.
  5. Enregistrer la behavior class dans le noyau.
Fenêtre de terminal
composer require goaop/framework

Composer installe le framework dans vendor/goaop/framework.

Les exemples de cette page utilisent l’arborescence suivante. Ils supposent que Composer charge automatiquement les classes de app/ et de src/, par exemple via la section autoload de votre composer.json.

app/ApplicationAspectKernel.php the kernel
public/index.php the front controller
src/ your application code, compiled by the framework
src/Aspect/MonitorAspect.php your first behavior class
var/cache/aop/ the cache of generated code
app/ApplicationAspectKernel.php
<?php
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
/**
* The application kernel
*/
class ApplicationAspectKernel extends AspectKernel
{
/**
* Register the behavior classes in the container
*/
protected function configureAop(AspectContainer $container): void
{
}
}

Le noyau gère en un seul endroit toutes les behavior classes de votre application. Étendez la classe abstraite Go\Core\AspectKernel et implémentez configureAop(). Elle reste vide pour l’instant ; vous y enregistrerez votre première behavior class plus bas.

public/index.php
<?php
include __DIR__ . '/../vendor/autoload.php'; // use composer
// Initialize the kernel
$applicationAspectKernel = ApplicationAspectKernel::getInstance();
$applicationAspectKernel->init([
'debug' => true, // use 'false' for production mode
'appDir' => __DIR__ . '/..', // Application root directory
'cacheDir' => __DIR__ . '/../var/cache/aop', // Cache directory
// Directories whose classes get behaviors; empty means all source files
'includePaths' => [
__DIR__ . '/../src/'
]
]);
// Your application starts here

Appelez init() une seule fois, juste après l’autoloader de Composer et avant que votre application ne charge ses propres classes. Ces quatre options suffisent pour démarrer :

Option Rôle
debug true active le mode développement. Utilisez false en production.
appDir La racine de l’application. Seuls les fichiers situés en dessous sont compilés. Par défaut, c’est le répertoire qui contient vendor/.
cacheDir L’emplacement où le code généré est écrit. Cette option est obligatoire.
includePaths Les répertoires à compiler. Un tableau vide signifie tout ce qui se trouve sous appDir.

Gardez includePaths restreint. Compiler le code des dépendances (vendor) est lent et rarement utile. Une clé d’option inconnue lève Go\Aop\Exception\InvalidConfigurationException : une faute de frappe échoue immédiatement au lieu d’être ignorée. La liste complète des options se trouve sur la page Configuration et CLI.

src/Aspect/MonitorAspect.php
<?php
namespace Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Before;
/**
* A monitoring behavior class
*/
class MonitorAspect implements Aspect
{
/**
* Method that will be called before real method
*/
#[Before("execution(public Example->*(*))")]
public function beforeMethodExecution(MethodInvocation $invocation): void
{
echo 'Calling Before Interceptor for: ',
$invocation,
' with arguments: ',
json_encode($invocation->getArguments()),
"<br>\n";
}
}

Une behavior class est une classe PHP ordinaire qui implémente Go\Aop\Aspect. Chaque behavior est une méthode publique qui porte un attribut de Go\Lang\Attribute indiquant quand elle s’exécute.

  • Un behavior #[Before] s’exécute avant l’appel intercepté. Les autres attributs sont #[After], #[AfterThrowing] et #[Around].
  • La chaîne passée à l’attribut est la matching rule. execution(public Example->*(*)) sélectionne l’exécution de toutes les méthodes publiques non statiques de la classe Example.
  • Le behavior reçoit un MethodInvocation, qui vous donne l’appel intercepté : getArguments() renvoie ses arguments, et l’invocation se convertit en une chaîne qui nomme la méthode.

Les méthodes de behavior doivent être public. Le framework les appelle directement sur l’instance de la behavior class : une méthode de behavior protected ou private est donc rejetée au chargement de la classe. Une méthode porte au plus un attribut de behavior.

app/ApplicationAspectKernel.php
<?php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
/**
* Register the behavior classes in the container
*/
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
}
}

Une behavior class est un service du conteneur du noyau. addLazyService() enregistre une factory. La compile step (étape de compilation) se contente de lire la behavior class : la factory s’exécute donc la première fois que l’un de ses behaviors s’exécute, pas avant.

Si vous préférez créer la behavior class dès le départ, enregistrez plutôt une instance :

$container->add(MonitorAspect::class, new MonitorAspect());

Les behavior classes peuvent aussi tirer leurs dépendances du conteneur PSR-11 de votre application, que vous rattachez au conteneur du noyau avec setDelegate(). La page Configuration et CLI montre comment faire.

Ajoutez une classe que la matching rule sélectionnera :

src/Example.php
<?php
class Example
{
public function greet(string $name): string
{
return "Hello, {$name}";
}
}

Utilisez-la ensuite dans le contrôleur frontal, après init() :

public/index.php
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();
echo $example->greet('World');

Ouvrez la page dans votre navigateur, ou lancez php public/index.php. Avant Hello, World apparaît la ligne écrite par le behavior, avec le nom de la méthode et ses arguments ["World"]. Example ne fait aucune référence à la behavior class : le behavior a été attaché à la classe quand l’autoloader l’a chargée et compilée.

Vous n’appelez jamais le behavior vous-même. Pour changer les méthodes sur lesquelles il s’exécute, vous modifiez la matching rule, pas les classes. La page Behaviors et matching rules explique quand s’exécute chaque behavior et donne la syntaxe complète des matching rules.

La console bin/aspect nécessite symfony/console :

Fenêtre de terminal
composer require symfony/console
vendor/bin/aspect debug:aspect public/index.php

debug:aspect liste les behavior classes enregistrées et leurs behaviors. Chaque commande bin/aspect prend le chemin du fichier qui initialise votre noyau, ici le contrôleur frontal, et exécute ce fichier. debug:advisor --advisor=... montre les appels interceptés que sélectionne un advisor (un behavior avec sa matching rule). Servez-vous de ces commandes quand un behavior ne s’exécute pas.

Vos classes sont compilées quand PHP les charge. Rien n’enveloppe vos objets à l’exécution, et aucun code n’est généré avec eval(). Chaque classe compilée est un fichier PHP ordinaire dans le répertoire de cache, et c’est ce fichier que PHP exécute.

Pour une classe compilée, le corps de la classe d’origine est déplacé dans un trait. Une classe générée, qui porte le nom de la classe d’origine, utilise ce trait : le nom de la classe, ses parents et self:: restent inchangés. Chaque méthode interceptée reçoit un call context (contexte d’appel) avec ses behaviors :

static $__joinPoint = InterceptorInjector::forMethod(
self::class,
'doSomething',
[
Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)),
],
$this->doSomethingOriginalAlias(...),
);

The::aspect() récupère l’instance de la behavior class dans le conteneur du noyau. ->beforeMethodExecution(...) est la méthode de behavior que vous avez écrite, référencée avec la syntaxe callable de première classe. Vous pouvez faire un Ctrl-clic dessus dans votre IDE, y poser un point d’arrêt et parcourir le code généré pas à pas. Le dernier argument pointe vers le corps de la méthode d’origine.

Les numéros de ligne sont conservés : les points d’arrêt Xdebug posés dans votre code d’origine fonctionnent toujours. Les attributs de la classe, de ses méthodes, paramètres, constantes et propriétés sont copiés dans le code généré, si bien que leur lecture par réflexion fonctionne comme avant. Les méthodes qu’aucune matching rule ne sélectionne s’exécutent sans aucun code d’interception.

cacheDir contient les sources compilées, les proxies, les caches d’advisors et la class map. Les chemins du cache reproduisent ceux des sources, relativement à appDir. Les fichiers sont du PHP ordinaire : vous pouvez les ouvrir, les comparer et les analyser avec vos outils de sécurité.

Ne versionnez pas le répertoire de cache. En développement, le framework le remplit au fur et à mesure que les classes sont chargées. En production, vous le construisez au moment du déploiement.

Avec 'debug' => true, chaque classe et chaque include passe par le stream filter du framework, qui le compile. Toute modification du fichier du noyau ou des fichiers de behavior classes invalide le cache, et les fichiers modifiés sont recompilés à la requête suivante. Il n’y a pas d’étape de build : modifiez une classe ou un behavior et rechargez la page.

Le mode développement est nettement plus lent que le mode production sur les requêtes à chaud. Ne l’utilisez pas en production.

Avec 'debug' => false, les classes compilées sont chargées depuis le cache via la class map de Composer. Le parseur et les transformateurs ne sont pas chargés sur les requêtes à chaud.

Pour le déploiement, construisez le cache une fois et demandez au noyau de lui faire confiance :

  1. Videz le répertoire de cache.

  2. Préchauffez le cache :

    Fenêtre de terminal
    vendor/bin/aspect cache:warmup:aop public/index.php

    La commande échoue lorsqu’un fichier ne peut pas être compilé : un script de déploiement s’arrête donc au lieu de livrer un cache incomplet. Les gros projets compilent plus vite en parallèle, par exemple avec --workers=8.

  3. Exécutez avec 'debug' => false et la fonctionnalité 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,
    ]);

Avec PREBUILT_CACHE, une requête ne compile jamais et n’écrit jamais dans le répertoire de cache : elle fonctionne donc aussi sur un système de fichiers en lecture seule. Le cache doit être complet : une classe située sous les chemins d’inclusion dont le cache n’a aucune trace fait échouer la requête avec une WeavingException. Reconstruisez le cache chaque fois que le code ou les behavior classes changent.

La page Production et performances traite d’OPcache, du préchargement, de Docker et de Kubernetes.

Si votre application tourne sur Symfony, Laravel ou Yii3, installez le bridge correspondant au lieu d’écrire vous-même le code du contrôleur frontal. Le bridge démarre le framework tôt dans le cycle de vie de l’application et vous permet d’enregistrer les behavior classes comme services du conteneur de votre framework. Consultez la page Intégrations, ou les dépôts goaop/goaop-symfony-bundle, goaop/goaop-laravel-bridge et goaop/goaop-yii3-bridge.

Vous migrez une application depuis la version 3.x ? Lisez d’abord la page Limitations et migration. Elle recense chaque changement.

Le dépôt du framework est une marketplace de plugins pour agents de codage. Son plugin goaop contient une Agent Skill qui apprend à un agent à écrire des behavior classes, des behaviors et des matching rules, à intégrer le framework, à déployer le cache et à trouver pourquoi un behavior ne s’exécute pas. Dans Claude Code :

/plugin marketplace add goaop/framework
/plugin install goaop@goaop

© 2026 Alexander Lisachenko