Aller au contenu
Documentation

Behaviors et matching rules

La référence complète pour écrire des behaviors, les middlewares dynamiques que le framework exécute autour de votre code, et les matching rules qui indiquent où ils s’appliquent.

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

Cette page couvre tout ce que vous écrivez quand vous travaillez avec le framework : les behavior classes (classes de comportement), les behaviors (comportements) qu’elles contiennent et qui s’exécutent comme middleware dynamique autour de votre code, le call context (contexte d’appel) que reçoit chaque behavior, et les matching rules (règles de correspondance) qui choisissent où il s’exécute. Si vous n’avez pas encore mis en place de noyau (kernel), commencez par Premiers pas. Pour des guides complets, du problème jusqu’au code qui fonctionne, voyez le behavior de mise en cache et le behavior de journalisation.

L’API du framework conserve les noms classiques : vous les rencontrerez dans le code, dans les noms de classes et dans les messages d’erreur. Cette documentation emploie les mots du quotidien et cite une fois le terme de l’API :

Dans cette documentation Dans l’API Ce que c’est
Behavior class (classe de comportement) Aspect Une classe qui implémente Go\Aop\Aspect et regroupe des behaviors liés
Behavior (comportement, middleware) Advice (greffon) Une méthode publique de la behavior class qui porte un attribut de Go\Lang\Attribute : #[Before], #[After], #[AfterThrowing] ou #[Around]
Matching rule (règle de correspondance) Pointcut (point de coupe) L’expression placée dans cet attribut, qui sélectionne où le behavior s’exécute
Call context (contexte d’appel) Joinpoint (point de jonction) Le moment intercepté (un appel de méthode, un accès à une propriété, la création d’un objet), transmis au behavior sous forme d’objet
Compile step (étape de compilation) Weaving (tissage) La transformation de vos classes en fichiers que PHP charge, avec les behaviors attachés
Class extension (extension de classe) Introduction Une interface et un trait ajoutés à des classes existantes
src/Aspect/ServiceAspect.php
namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\AfterThrowing;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
class ServiceAspect 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->debug($invocation . ' took ' . (hrtime(true) - $start) . ' ns');
}
}
#[AfterThrowing('execution(public App\Service\*->*(*))')]
public function logFailure(MethodInvocation $invocation, \Throwable $exception): void
{
$this->logger->error($invocation . ' failed: ' . $exception->getMessage());
}
}

Une behavior class est une classe PHP ordinaire qui implémente Go\Aop\Aspect. Elle contient une logique, comme la journalisation, la mise en cache, les contrôles de sécurité ou les transactions, qui serait sinon recopiée dans de nombreuses classes. Chacun de ses behaviors s’exécute comme un middleware autour du code que sélectionne sa matching rule : measure() ci-dessus enveloppe chaque méthode publique de App\Service, et logFailure() s’exécute quand l’une d’elles lève une exception. Comme il s’agit d’une classe ordinaire, vous pouvez utiliser l’injection par constructeur, un état privé, des traits et tout ce que PHP offre par ailleurs.

L’attribut d’un behavior indique quand il s’exécute par rapport à l’appel intercepté.

Attribut S’exécute
#[Before] Avant l’appel. Il peut modifier les arguments avec setArguments().
#[After] Après l’appel, y compris quand celui-ci lève une exception (comme finally).
#[AfterThrowing] Quand l’appel lève une exception. Il reçoit l’exception en second argument ; l’exception est ensuite relancée.
#[Around] À la place de l’appel, comme le fait un middleware. Il décide s’il appelle proceed(), et sa valeur de retour devient le résultat.

Les quatre attributs se trouvent dans l’espace de noms Go\Lang\Attribute et prennent une matching rule en argument.

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

Un behavior Before s’exécute juste avant la méthode d’origine. Utilisez-le pour valider les entrées ou vérifier les permissions. Pour changer ce que reçoit la méthode d’origine, remplacez les arguments :

#[Before('execution(public App\Service\UserService->rename(*))')]
public function trimName(MethodInvocation $invocation): void
{
$arguments = $invocation->getArguments();
$arguments[0] = trim($arguments[0]);
$invocation->setArguments($arguments);
}

getArguments() liste les arguments par position : vous y accédez donc par index.

use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\After;
#[After('execution(public App\Service\ImportService->run(*))')]
public function releaseLock(MethodInvocation $invocation): void
{
$this->lock->release();
}

Un behavior After fonctionne comme un bloc finally : il s’exécute que la méthode se termine normalement ou lève une exception. Utilisez-le pour libérer des ressources ou arrêter des chronomètres.

use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\AfterThrowing;
#[AfterThrowing('execution(public App\Service\*->*(*))')]
public function logFailure(MethodInvocation $invocation, \Throwable $exception): void
{
$this->logger->error($invocation . ' failed: ' . $exception->getMessage());
}

Un behavior AfterThrowing ne s’exécute que lorsque l’appel lève une exception. Il reçoit l’exception en second argument. Le framework relance l’exception après le behavior : l’appelant la voit donc toujours. Utilisez-le pour journaliser les erreurs ou envoyer des alertes.

use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
#[Around('execution(public App\Service\*->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->debug($invocation . ' took ' . (hrtime(true) - $start) . ' ns');
}
}

Un behavior Around s’exécute à la place de l’appel, comme un middleware dans une pile HTTP. Vous appelez proceed() pour passer la main au code d’origine, et ce que renvoie le behavior devient le résultat. C’est ce qui fait d’Around le type le plus puissant : il décide si le code d’origine s’exécute, peut modifier les arguments avant proceed(), peut changer la valeur de retour et peut intercepter les exceptions. Utilisez-le pour la mise en cache, les transactions et les nouvelles tentatives (retry).

Si vous n’appelez pas proceed(), la méthode d’origine ne s’exécute pas :

#[Around('execution(public App\Service\ReportService->build(*))')]
public function cacheReport(MethodInvocation $invocation): mixed
{
$key = $invocation . json_encode($invocation->getArguments());
return $this->reports[$key] ??= $invocation->proceed();
}

Chaque behavior reçoit un objet qui décrit l’appel intercepté : ses arguments, l’objet sur lequel il s’exécute, et proceed() pour continuer. Sa classe dépend de ce que sélectionne la matching rule.

Classe Reçue pour Méthodes principales
MethodInvocation execution() de méthodes dynamiques et statiques getThis(), getScope(), getMethod(), getArguments(), setArguments(), proceed()
FunctionInvocation execution() de fonctions d’un espace de noms getFunction(), getArguments(), setArguments(), proceed()
FieldAccess access() de propriétés getThis(), getField(), getAccessType(), getValue(), getValueToSet(), proceed()
ConstructorInvocation initialization() getConstructor(), getArguments(), getThis() (null tant que l’objet n’existe pas), proceed()

Toutes se trouvent dans Go\Aop\Intercept. Un MethodInvocation peut être utilisé comme une chaîne, comme le font les exemples ci-dessus dans leurs messages de log.

Ces classes déclarent des types @template : PHPStan et les IDE connaissent ainsi les types de getThis() et de proceed(). Écrivez les types concrets dans le docblock de votre behavior :

use App\Model\Order;
use App\Service\OrderService;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
/**
* @param MethodInvocation<OrderService, Order> $invocation
*/
#[Around('execution(public App\Service\OrderService->place(*))')]
public function auditOrder(MethodInvocation $invocation): Order
{
$order = $invocation->proceed();
// …
return $order;
}

Ici, MethodInvocation<OrderService, Order> indique à l’analyseur que getThis() est un OrderService et que proceed() renvoie un Order.

Attacher un behavior n’a rien de magique. Pour chaque méthode interceptée, le framework génère une simple chaîne de middlewares. Chaque behavior y est référencé par une closure créée avec la syntaxe callable de première classe, directement sur l’instance de la behavior class :

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, et ->beforeMethodExecution(...) est la méthode de behavior que vous avez écrite. 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, comme s’il avait été écrit à la main. Les call contexts sont construits à la compilation et mis en cache dans le code généré : il n’y a ni réflexion ni analyse d’attributs à l’exécution. Voir Debuggable pour en savoir plus sur le code généré.

Les behaviors enregistrés dans le conteneur sous forme de simples closures, et non comme méthodes d’une behavior class, sont attachés via l’accesseur paresseux The::advice(). Celui-ci recherche l’entrée enregistrée par son identifiant et la déballe jusqu’à la closure brute :

Interceptor::around(The::advice('advisor.Demo\Aspect\DynamicMethodsAspect->aroundMagicMethods')),

Une matching rule est une expression qui sélectionne où un behavior s’exécute : exécutions de méthodes, accès à des propriétés, appels de fonctions ou création d’objets. C’est l’argument de l’attribut du behavior :

#[Before('execution(public App\Service->save(*))')]

Le playground vous permet d’essayer des règles sur un fichier PHP ; cette section en est la référence complète.

Règle Sélectionne
execution(modifiers Class->method(*)) L’exécution d’une méthode dynamique
execution(modifiers Class::method(*)) L’exécution d’une méthode statique
execution(Namespace\function(*)) Les appels d’une fonction système depuis cet espace de noms
access(modifiers Class->property) Les lectures et écritures d’une propriété d’instance
within(ClassFilter) Tous les membres (méthodes et propriétés) des classes correspondantes
initialization(ClassFilter) La création d’objets avec new
staticinitialization(ClassFilter) Le premier chargement des classes correspondantes
@execution(Attribute) Les méthodes qui portent l’attribut
@access(Attribute) Les propriétés qui portent l’attribut
@within(Attribute) Tous les membres des classes qui portent l’attribut
matchInherited() Uniquement les membres hérités d’une classe parente ou importés d’un trait ; !matchInherited() les exclut
matchReturningByReference() Les méthodes et fonctions déclarées function &name() ; !matchReturningByReference() les exclut
$this->pointcutName Une règle nommée, déclarée avec #[Pointcut] sur une méthode de la même behavior class
Aspect\Class->pointcutName Une règle nommée d’une autre behavior class

La liste d’arguments est toujours (*) : les arguments n’entrent pas dans la correspondance.

Attention au séparateur : -> sélectionne les méthodes dynamiques, :: les méthodes statiques.

execution(public App\Service\OrderService->place(*))
execution(public App\Util\Money::format(*))

Pour intercepter les appels de méthodes magiques, attachez le behavior à __call lui-même :

execution(public Foo->__call(*))
Motif Signification
* N’importe quels caractères d’une partie de nom, y compris aucun, sans jamais franchir un \ : get* (y compris get), *Service (y compris Service), App\*\Controller (exactement un niveau d’espace de noms entre les deux)
** N’importe quelle profondeur d’espace de noms : App\** désigne toutes les classes sous App, **->*(*) toutes les méthodes
a|b Des alternatives au sein d’une partie de nom, par exemple get*|is*. Elles s’appliquent à la partie où elles sont écrites : App\Cart|Order désigne App\Cart ou App\Order, jamais un Order global. Pour des classes d’espaces de noms différents, joignez deux règles avec ||
Foo+ Foo lui-même, ses sous-classes et les classes qui l’implémentent, ainsi que les classes qui utilisent le trait Foo (directement ou via une classe parente)

Les noms sont sensibles à la casse. Écrivez les espaces de noms avec une seule barre oblique inverse ; dans une chaîne PHP entre apostrophes, aucun échappement n’est nécessaire.

execution(public **->save*(*))
execution(public App\Repository\*Repository->find*|get*(*))
execution(public App\Contract\Cacheable+->*(*))

Les règles de méthodes et de propriétés acceptent ces modificateurs :

  • public, protected, private
  • final, readonly
  • les modificateurs de visibilité asymétrique private(set) et protected(set)

Combinez les alternatives avec | :

execution(public|protected App\Service->*(*))

Des modificateurs séparés par des espaces doivent tous être présents, et | est prioritaire sur l’espace. final public|protected sélectionne les méthodes finales qui sont publiques ou protégées. Un seul groupe d’alternatives est pris en charge par motif.

Les propriétés statiques ne sont jamais interceptées, pas plus que les propriétés readonly ou celles qui ont déjà des hooks. La section sur l’interception des propriétés, plus bas, liste tous les cas ; les raisons sont dans Limitations et migration.

Un motif de méthode ou de fonction peut restreindre le type de retour déclaré :

execution(public App\Repo->find*(*): App\Entity|null)

Les types union s’écrivent avec |, les types intersection avec &, et ?Foo équivaut à Foo|null.

Opérateur Signification
&& Les deux correspondent
|| L’une ou l’autre correspond
! Négation
( ) Regroupement
within(App\**) && !execution(public **->__construct(*))

Les commentaires commencent par // et vont jusqu’à la fin de la ligne. Ils sont utiles dans les longues expressions sur plusieurs lignes :

#[Around('
execution(public App\Service\**->*(*)) // every public service method
&& !matchReturningByReference() // skip function &name()
&& !matchInherited() // skip inherited and trait methods
')]
public function trace(MethodInvocation $invocation): mixed
{
return $invocation->proceed();
}

Déclarez une règle une seule fois et référencez-la depuis plusieurs behaviors :

src/Aspect/HealthyLiveAspect.php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\After;
use Go\Lang\Attribute\Before;
use Go\Lang\Attribute\Pointcut;
class HealthyLiveAspect implements Aspect
{
#[Pointcut('execution(public App\Human->eat(*))')]
protected function humanEat(): void {}
#[Before('$this->humanEat')]
public function washUpBeforeEat(MethodInvocation $invocation): void { /* ... */ }
#[After('$this->humanEat')]
public function cleanTeethAfterEat(MethodInvocation $invocation): void { /* ... */ }
}

La méthode #[Pointcut] a un corps vide ; seul son attribut compte. Référencez-la sous la forme $this->humanEat depuis la même behavior class. Depuis une autre, utilisez le nom de la classe qui la déclare, par exemple App\Aspect\HealthyLiveAspect->humanEat.

@execution, @access et @within sélectionnent les membres d’après les attributs PHP qu’ils portent. Vous marquez ainsi le code qui doit recevoir un behavior, au lieu de le sélectionner par son nom :

src/Attribute/Cacheable.php
namespace App\Attribute;
#[\Attribute(\Attribute::TARGET_METHOD)]
final class Cacheable {}
src/Aspect/CachingAspect.php
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
class CachingAspect implements Aspect
{
#[Around('@execution(App\Attribute\Cacheable)')]
public function cache(MethodInvocation $invocation): mixed
{
// …
return $invocation->proceed();
}
}

@access(Attribute) fait de même pour les propriétés, et @within(Attribute) sélectionne tous les membres des classes qui portent l’attribut. Les attributs des classes compilées sont copiés dans le code généré avec leurs arguments d’origine : leur lecture à l’exécution fonctionne donc comme avant. Le behavior de mise en cache construit un #[Cacheable(ttl: 600)] complet sur cette règle.

use Go\Aop\Intercept\FieldAccess;
use Go\Aop\Intercept\FieldAccessType;
use Go\Lang\Attribute\Around;
#[Around('access(public App\Entity\User->email)')]
public function normalizeEmail(FieldAccess $access): mixed
{
if ($access->getAccessType() === FieldAccessType::Write) {
return strtolower($access->proceed());
}
return $access->proceed();
}

Les règles access(...) interceptent les lectures et écritures de propriétés d’instance grâce aux property hooks natifs de PHP 8.4, placés sur les classes proxy générées. Le behavior reçoit un FieldAccess. Pour une écriture, proceed() renvoie la valeur qui est stockée : un behavior Around peut donc la modifier, comme le fait l’exemple.

Ce qui peut être intercepté :

  • les propriétés déclarées dans la classe compilée elle-même, y compris les propriétés promues par le constructeur (y compris celles marquées final, sous PHP 8.5). L’affectation faite par le constructeur est interceptée comme une écriture.
  • les propriétés publiques et protégées héritées de classes parentes

Ce qui est ignoré :

  • les propriétés static, readonly et celles qui ont déjà des hooks
  • les propriétés final héritées de classes parentes
  • les propriétés private héritées

Pour les propriétés de type tableau, le proxy n’émet qu’un hook &get par référence, sans set. Les modifications indirectes comme array_push($this->items, ...) restent ainsi valides.

Quand Doctrine hydrate une entité ou l’écrit en base (flush), il lit et écrit les valeurs brutes des propriétés : les behaviors de propriété ne s’exécutent donc que pour les accès faits par votre propre code. Voir Intégrations pour la configuration de Doctrine, et la page de la fonctionnalité Property hooks pour une vue d’ensemble.

src/Aspect/SerializableAspect.php
use App\Model\JsonSerializableTrait;
use Go\Aop\Aspect;
use Go\Lang\Attribute\DeclareParents;
class SerializableAspect implements Aspect
{
#[DeclareParents('within(App\Model\*)', interfaceName: \JsonSerializable::class, traitName: JsonSerializableTrait::class)]
protected null $jsonSerializable;
}
src/Model/JsonSerializableTrait.php
namespace App\Model;
trait JsonSerializableTrait
{
public function jsonSerialize(): mixed
{
return get_object_vars($this);
}
}

Une class extension change les capacités qu’exposent des classes existantes, là où un behavior change ce qui se passe quand leur code s’exécute. #[DeclareParents] sur une propriété de la behavior class ajoute aux classes correspondantes une interface et un trait qui l’implémente. Ici, chaque classe de App\Model devient JsonSerializable sans qu’aucune ne soit modifiée. Cela fonctionne aussi pour les classes de paquets Composer, voir la page de la fonctionnalité Class extensions.

use Go\Aop\Intercept\FunctionInvocation;
use Go\Lang\Attribute\Around;
#[Around('execution(App\Service\file_get_contents(*))')]
public function logRead(FunctionInvocation $invocation): mixed
{
$this->logger->debug('Reading ' . $invocation->getArguments()[0]);
return $invocation->proceed();
}

execution(App\Service\file_get_contents(*)) intercepte les appels de file_get_contents() depuis le code de l’espace de noms App\Service. Le behavior reçoit un FunctionInvocation.

Les proxies des fonctions interceptées sont générés avec declare(strict_types=1), un fichier par espace de noms. Les arguments sont convertis selon le mode du fichier appelant avant l’entrée dans le proxy.

use Go\Aop\Intercept\ConstructorInvocation;
use Go\Lang\Attribute\Around;
#[Around('initialization(App\Model\Order)')]
public function trackOrderCreation(ConstructorInvocation $invocation): mixed
{
$order = $invocation->proceed();
// …
return $order;
}

initialization(App\Model\Order) intercepte new Order(...) dans les fichiers compilés. Le behavior reçoit un ConstructorInvocation. Son getThis() renvoie null tant que l’objet n’existe pas.

staticinitialization(App\Model\*) s’exécute une seule fois, après le chargement de la classe.

Les behavior classes sont des services du conteneur du noyau. Enregistrez-les dans la méthode configureAop() de votre noyau, de préférence comme services différés :

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

addLazyService() enregistre une factory. La compile step n’instancie jamais les behavior classes : chacune est créée la première fois que l’un de ses behaviors s’exécute, sous forme d’objet paresseux natif (native lazy object) de PHP 8.4. add() enregistre une instance que vous avez déjà construite.

La factory reçoit le conteneur du noyau, un AspectContainer. C’est un conteneur PSR-11 : vous pouvez donc y récupérer les dépendances de la behavior class :

use Go\Core\AspectContainer;
use Psr\Log\LoggerInterface;
$container->addLazyService(
ServiceAspect::class,
static fn(AspectContainer $c) => new ServiceAspect($c->getService(LoggerInterface::class)),
);

Les services du conteneur PSR-11 de votre application deviennent disponibles une fois que vous l’avez rattaché au conteneur du noyau avec setDelegate(). Les bridges pour Symfony, Laravel et Yii3 enregistrent les behavior classes à votre place ; voir Intégrations. Les options du noyau sont décrites dans Configuration et CLI.

Un behavior s’exécute une seule fois par exécution de méthode, quel que soit le nombre de classes compilées dans la hiérarchie. Une méthode qu’une classe compilée ne fait qu’hériter est interceptée par l’ancêtre compilé le plus proche où la règle la sélectionne (au plus haut, la classe qui déclare la méthode) ; la sous-classe hérite de cette méthode interceptée et ne redéfinit rien.

Lorsqu’un tel ancêtre n’existe pas, par exemple pour une classe parente située hors de includePaths ou que la règle ne sélectionne pas, la sous-classe intercepte elle-même la méthode héritée.

Pour restreindre une règle aux membres qu’une classe déclare elle-même, ajoutez !matchInherited(). Cela exclut les membres hérités d’une classe parente et ceux importés d’un trait.

Quelques sortes de méthodes ne peuvent pas recevoir de behavior, ou fonctionnent différemment quand elles en reçoivent un. La liste complète, avec les raisons, se trouve dans Limitations et migration. En bref :

  • Retour par référence. Une méthode ou une fonction déclarée function &name() ne peut pas être interceptée ; sa compilation échoue avec une WeavingException. Excluez ces méthodes d’une règle large avec && !matchReturningByReference().
  • Méthodes de trait avec #[\Override]. Une méthode qu’une classe importe d’un trait et qui porte #[\Override] ne peut pas être interceptée dans cette classe ; sa compilation échoue avec une WeavingException. Excluez-la avec && !matchInherited(), ou attachez le behavior au trait lui-même, par exemple execution(public HelloTrait->hello(*)), qui s’applique dans toutes les classes utilisant le trait.
  • Générateurs. Pour une méthode qui contient yield, le behavior s’exécute à l’appel de la méthode, et proceed() renvoie l’objet Generator. Le behavior ne voit pas les valeurs produites.
  • Arguments. getArguments() liste les arguments par position. Un paramètre variadique par référence (&...$values) est transmis par valeur à la méthode d’origine.
  • #[\SensitiveParameter]. Deux frames internes de la pile, entre le call context et la méthode d’origine, contiennent encore le tableau d’arguments dans Throwable::getTrace(). Avec zend.exception_ignore_args=On, la valeur par défaut en production, aucune frame ne contient d’arguments.
  • Propriétés. Les propriétés statiques, readonly et celles qui ont déjà des hooks ne sont pas interceptées, pas plus que les propriétés final ou private héritées.

© 2026 Alexander Lisachenko