Behaviors e matching rules
A referência completa para escrever behaviors, o middleware dinâmico que o framework roda em torno do seu código, e as matching rules que dizem onde eles se aplicam.
Traduzido do inglês. A página em inglês é a referência. Ler o original
Esta página cobre tudo o que você escreve ao trabalhar com o framework: as behavior classes (classes de comportamento), os behaviors (comportamentos) dentro delas, que rodam como middleware dinâmico em torno do seu código, o call context (contexto de chamada) que cada behavior recebe e as matching rules (regras de correspondência) que selecionam onde ele roda. Se você ainda não configurou um kernel, comece por Primeiros passos. Para exemplos completos, do problema ao código funcionando, veja o behavior de cache e o behavior de logging.
Termos desta página
Seção intitulada “Termos desta página”A API do framework mantém os nomes clássicos, então você vai encontrá-los no código, nos nomes de classes e nas mensagens de erro. Esta documentação usa as palavras do dia a dia e cita o termo da API uma vez:
| Nesta documentação | Na API | O que é |
|---|---|---|
| Behavior class (classe de comportamento) | Aspect (aspecto) | Uma classe que implementa Go\Aop\Aspect e agrupa behaviors relacionados |
| Behavior (comportamento), um middleware | Advice (conselho) | Um método público da behavior class com um atributo de Go\Lang\Attribute: #[Before], #[After], #[AfterThrowing] ou #[Around] |
| Matching rule (regra de correspondência) | Pointcut (ponto de corte) | A expressão nesse atributo que seleciona onde o behavior roda |
| Call context (contexto de chamada) | Joinpoint (ponto de junção) | O momento interceptado (uma chamada de método, um acesso a propriedade, a criação de um objeto), passado ao behavior como objeto |
| Compile step (etapa de compilação) | Weaving (entrelaçamento) | Transformar suas classes nos arquivos que o PHP carrega, com os behaviors anexados |
| Class extension (extensão de classe) | Introduction (introdução) | Uma interface e uma trait adicionadas a classes existentes |
Behavior classes
Seção intitulada “Behavior classes”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()); }}Uma behavior class é uma classe PHP comum que implementa Go\Aop\Aspect. Ela concentra lógica como logging, cache, verificações de segurança ou transações, que de outro modo seria copiada em muitas classes. Cada um dos seus behaviors roda como middleware em torno do código que sua matching rule seleciona: measure(), acima, envolve todo método público de App\Service, e logFailure() roda quando um deles lança uma exceção. Como é uma classe comum, você pode usar injeção via construtor, estado privado, traits e tudo mais que o PHP oferece.
Quando um behavior roda
Seção intitulada “Quando um behavior roda”O atributo de um behavior diz quando ele roda em relação à chamada interceptada.
| Atributo | Roda |
|---|---|
#[Before] |
Antes da chamada. Pode mudar os argumentos com setArguments(). |
#[After] |
Depois da chamada, inclusive quando ela lança uma exceção (como finally). |
#[AfterThrowing] |
Quando a chamada lança uma exceção. Recebe a exceção como segundo argumento; depois disso, a exceção é relançada. |
#[Around] |
No lugar da chamada, como faz um middleware. Decide se chama proceed(), e o valor que retorna vira o resultado. |
Os quatro atributos ficam no namespace Go\Lang\Attribute e recebem uma matching rule como argumento.
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"; }}Um behavior Before roda logo antes do método original. Use-o para validar entradas ou verificar permissões. Para mudar o que o método original recebe, substitua os argumentos:
#[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() lista os argumentos por posição, então você os acessa pelo índice.
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();}Um behavior After funciona como um bloco finally: roda tanto se o método retornar normalmente quanto se lançar uma exceção. Use-o para liberar recursos ou parar timers.
AfterThrowing
Seção intitulada “AfterThrowing”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());}Um behavior AfterThrowing roda só quando a chamada lança uma exceção. Ele recebe a exceção como segundo argumento. O framework relança a exceção depois do behavior, então quem chamou continua vendo a exceção. Use-o para registrar erros em log ou enviar alertas.
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'); }}Um behavior Around roda no lugar da chamada, como um middleware numa pilha HTTP. Você chama proceed() para passar o controle ao código original, e o que o behavior retornar vira o resultado. Isso faz do Around o tipo mais poderoso: ele decide se o original chega a rodar, pode mudar os argumentos antes de proceed(), pode mudar o valor de retorno e pode capturar exceções. Use-o para cache, transações e lógica de retry.
Se você não chamar proceed(), o método original não roda:
#[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();}O call context
Seção intitulada “O call context”Todo behavior recebe um objeto que descreve a chamada interceptada: seus argumentos, o objeto em que ela roda e proceed() para continuar. A classe desse objeto depende do que a matching rule seleciona.
Referência do call context
Seção intitulada “Referência do call context”| Classe | Recebida para | Principais métodos |
|---|---|---|
MethodInvocation |
execution() de métodos dinâmicos e estáticos |
getThis(), getScope(), getMethod(), getArguments(), setArguments(), proceed() |
FunctionInvocation |
execution() de funções com namespace |
getFunction(), getArguments(), setArguments(), proceed() |
FieldAccess |
access() de propriedades |
getThis(), getField(), getAccessType(), getValue(), getValueToSet(), proceed() |
ConstructorInvocation |
initialization() |
getConstructor(), getArguments(), getThis() (null antes de o objeto existir), proceed() |
Todas ficam em Go\Aop\Intercept. Um MethodInvocation pode ser usado como string, como os exemplos acima fazem nas mensagens de log.
Tipos genéricos
Seção intitulada “Tipos genéricos”Essas classes declaram tipos @template, então o PHPStan e as IDEs conhecem os tipos de getThis() e proceed(). Escreva os tipos concretos no docblock do seu 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;}Aqui, MethodInvocation<OrderService, Order> informa ao analisador que getThis() é um OrderService e que proceed() retorna um Order.
Como os behaviors viram middleware
Seção intitulada “Como os behaviors viram middleware”Não há mágica em anexar um behavior. Para cada método interceptado, o framework gera uma cadeia de middleware comum. Cada behavior é referenciado como uma closure criada com a sintaxe de first-class callable, direto na instância da behavior class:
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() busca a instância da behavior class no container do kernel, e ->beforeMethodExecution(...) é o método de behavior que você escreveu. Você pode dar Ctrl-clique nele na IDE, colocar um breakpoint dentro dele e percorrer o código gerado passo a passo como se tivesse sido escrito à mão. Os call contexts são montados em tempo de compilação e ficam em cache no código gerado, então não há reflection nem leitura de atributos em tempo de execução. Veja Debuggable para saber mais sobre o código gerado.
Behaviors registrados no container como closures simples, e não como métodos de uma behavior class, são anexados pelo acessor lazy The::advice(). Ele busca a entrada registrada pelo identificador e a desembrulha até a closure pura:
Interceptor::around(The::advice('advisor.Demo\Aspect\DynamicMethodsAspect->aroundMagicMethods')),Matching rules
Seção intitulada “Matching rules”Uma matching rule é uma expressão que seleciona onde um behavior roda: execuções de métodos, acessos a propriedades, chamadas de funções ou criação de objetos. Ela é o argumento do atributo do behavior:
#[Before('execution(public App\Service->save(*))')]O playground permite testar regras num arquivo PHP; esta seção é a referência completa.
Tipos de regras
Seção intitulada “Tipos de regras”| Regra | Seleciona |
|---|---|
execution(modifiers Class->method(*)) |
Execução de um método dinâmico |
execution(modifiers Class::method(*)) |
Execução de um método estático |
execution(Namespace\function(*)) |
Chamadas de uma função do sistema a partir desse namespace |
access(modifiers Class->property) |
Leituras e escritas de uma propriedade de instância |
within(ClassFilter) |
Todo membro (métodos e propriedades) das classes correspondentes |
initialization(ClassFilter) |
Criação de objetos com new |
staticinitialization(ClassFilter) |
O primeiro carregamento das classes correspondentes |
@execution(Attribute) |
Métodos que têm o atributo |
@access(Attribute) |
Propriedades que têm o atributo |
@within(Attribute) |
Todo membro das classes que têm o atributo |
matchInherited() |
Só membros herdados de uma classe pai ou importados de uma trait; !matchInherited() os exclui |
matchReturningByReference() |
Métodos e funções declarados como function &name(); !matchReturningByReference() os exclui |
$this->pointcutName |
Uma regra nomeada, declarada com #[Pointcut] num método da mesma behavior class |
Aspect\Class->pointcutName |
Uma regra nomeada de outra behavior class |
A lista de argumentos é sempre (*): os argumentos não entram na correspondência.
Repare no separador: -> seleciona métodos dinâmicos, :: seleciona os estáticos.
execution(public App\Service\OrderService->place(*))execution(public App\Util\Money::format(*))Para interceptar chamadas de métodos mágicos, anexe o behavior ao próprio __call:
execution(public Foo->__call(*))Nomes e curingas
Seção intitulada “Nomes e curingas”| Padrão | Significado |
|---|---|
* |
Quaisquer caracteres de uma parte do nome, inclusive nenhum, sem nunca atravessar um \: get* (também get), *Service (também Service), App\*\Controller (exatamente um nível de namespace no meio) |
** |
Qualquer profundidade de namespace: App\** é toda classe abaixo de App, **->*(*) é todo método |
a|b |
Alternativas dentro de uma parte do nome, por exemplo get*|is*. Valem para a parte em que foram escritas: App\Cart|Order é App\Cart ou App\Order, nunca um Order global. Para classes de namespaces diferentes, junte duas regras com || |
Foo+ |
O próprio Foo, suas subclasses e implementações, e as classes que usam a trait Foo (diretamente ou por meio de uma classe pai) |
Os nomes diferenciam maiúsculas de minúsculas. Escreva os namespaces com uma única barra invertida; numa string PHP com aspas simples, não é preciso escapar nada.
execution(public **->save*(*))execution(public App\Repository\*Repository->find*|get*(*))execution(public App\Contract\Cacheable+->*(*))Modificadores
Seção intitulada “Modificadores”As regras de métodos e de propriedades aceitam estes modificadores:
public,protected,privatefinal,readonly- os modificadores de visibilidade assimétrica
private(set)eprotected(set)
Combine alternativas com |:
execution(public|protected App\Service->*(*))Modificadores separados por espaço precisam estar todos presentes, e | tem precedência sobre o espaço. final public|protected corresponde a métodos final que são public ou protected. Há suporte a um grupo de alternativas por padrão.
Propriedades estáticas nunca são interceptadas, nem propriedades readonly ou propriedades que já têm hooks. A seção sobre interceptação de propriedades, mais abaixo, lista todos os casos; os motivos estão em Limitações e atualização.
Tipos de retorno
Seção intitulada “Tipos de retorno”Um padrão de método ou de função pode restringir o tipo de retorno declarado:
execution(public App\Repo->find*(*): App\Entity|null)Tipos união usam |, tipos interseção usam &, e ?Foo é o mesmo que Foo|null.
Combinando regras
Seção intitulada “Combinando regras”| Operador | Significado |
|---|---|
&& |
As duas correspondem |
|| |
Qualquer uma corresponde |
! |
Negação |
( ) |
Agrupamento |
within(App\**) && !execution(public **->__construct(*))Comentários
Seção intitulada “Comentários”Comentários começam com // e vão até o fim da linha. Ajudam em expressões longas, de várias linhas:
#[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();}Regras nomeadas
Seção intitulada “Regras nomeadas”Declare uma regra uma vez e faça referência a ela em vários behaviors:
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 { /* ... */ }}O método com #[Pointcut] tem corpo vazio; só o atributo importa. Na mesma behavior class, faça referência a ele como $this->humanEat. Em outra, use o nome da classe que o declara, por exemplo App\Aspect\HealthyLiveAspect->humanEat.
Regras por atributo
Seção intitulada “Regras por atributo”@execution, @access e @within selecionam membros pelos atributos PHP que eles têm. Assim você marca o código que deve receber um behavior, em vez de selecioná-lo pelo nome:
namespace App\Attribute;
#[\Attribute(\Attribute::TARGET_METHOD)]final class Cacheable {}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) faz o mesmo para propriedades, e @within(Attribute) seleciona todo membro das classes que têm o atributo. Os atributos das classes compiladas são copiados para o código gerado com seus argumentos originais, então lê-los em tempo de execução funciona como antes. O behavior de cache monta um #[Cacheable(ttl: 600)] completo sobre essa regra.
Behaviors em propriedades
Seção intitulada “Behaviors em propriedades”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();}Regras access(...) interceptam leituras e escritas de propriedades de instância por meio de property hooks nativos do PHP 8.4 nas classes proxy geradas. O behavior recebe um FieldAccess. Numa escrita, proceed() retorna o valor que será armazenado, então um behavior Around pode alterá-lo, como faz o exemplo.
O que pode ser interceptado:
- propriedades declaradas na própria classe compilada, inclusive propriedades promovidas no construtor (também as
final, no PHP 8.5). A atribuição feita pelo construtor é interceptada como escrita. - propriedades public e protected herdadas de classes pai
O que fica de fora:
- propriedades
static,readonlye as que já têm hooks - propriedades
finalherdadas de classes pai - propriedades
privateherdadas
Para propriedades do tipo array, o proxy emite apenas um hook &get por referência, sem set. Isso mantém válidas modificações indiretas como array_push($this->items, ...).
Quando o Doctrine hidrata ou faz flush de uma entidade, ele lê e grava os valores brutos das propriedades, então os behaviors de propriedade só rodam nos acessos feitos pelo seu próprio código. Veja Integrações para a configuração do Doctrine e a página da feature Property hooks para uma visão geral.
Class extensions
Seção intitulada “Class extensions”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;}namespace App\Model;
trait JsonSerializableTrait{ public function jsonSerialize(): mixed { return get_object_vars($this); }}Uma class extension muda as capacidades que classes existentes expõem, enquanto um behavior muda o que acontece quando o código delas roda. #[DeclareParents] numa propriedade da behavior class adiciona às classes correspondentes uma interface e uma trait que a implementa. Aqui, toda classe de App\Model passa a ser JsonSerializable sem que nenhuma delas seja editada. Isso também funciona com classes de pacotes Composer; veja a página da feature Class extensions.
Behaviors em chamadas de funções
Seção intitulada “Behaviors em chamadas de funções”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(*)) intercepta as chamadas de file_get_contents() feitas por código no namespace App\Service. O behavior recebe um FunctionInvocation.
Os proxies das funções interceptadas são gerados com declare(strict_types=1), um arquivo por namespace. Os argumentos são convertidos conforme o modo do arquivo chamador antes de entrar no proxy.
Criação de objetos
Seção intitulada “Criação de objetos”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) intercepta new Order(...) nos arquivos compilados. O behavior recebe um ConstructorInvocation. O getThis() dele retorna null antes de o objeto existir.
staticinitialization(App\Model\*) roda uma vez, depois que a classe é carregada.
Registrando behavior classes
Seção intitulada “Registrando behavior classes”As behavior classes são serviços do container do kernel. Registre-as no configureAop() do seu kernel, de preferência como serviços adiados:
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() registra uma factory. A compile step nunca instancia behavior classes: cada uma é criada quando um dos seus behaviors roda pela primeira vez, como um lazy object nativo do PHP 8.4. add() registra uma instância que você já construiu.
Dependências
Seção intitulada “Dependências”A factory recebe o container do kernel, um AspectContainer. Ele é um container PSR-11, então você pode tirar dele as dependências da behavior class:
use Go\Core\AspectContainer;use Psr\Log\LoggerInterface;
$container->addLazyService( ServiceAspect::class, static fn(AspectContainer $c) => new ServiceAspect($c->getService(LoggerInterface::class)),);Os serviços do container PSR-11 da sua própria aplicação ficam disponíveis assim que você o liga ao container do kernel com setDelegate(). As bridges para Symfony, Laravel e Yii3 registram as behavior classes por você; veja Integrações. As opções do kernel estão em Configuração e CLI.
Métodos herdados
Seção intitulada “Métodos herdados”Um behavior roda uma vez por execução de método, não importa quantas classes da hierarquia sejam compiladas. Um método que uma classe compilada apenas herda é interceptado pelo ancestral compilado mais próximo em que a regra corresponde (até a classe que declara o método); a subclasse herda esse método interceptado e não sobrescreve nada.
Quando não existe esse ancestral, como no caso de uma classe pai fora de includePaths ou de uma em que a regra não corresponde, a própria subclasse intercepta o método herdado.
Para restringir uma regra aos membros que a classe declara ela mesma, adicione !matchInherited(). Isso exclui membros herdados de uma classe pai e membros importados de uma trait.
Limitações
Seção intitulada “Limitações”Alguns tipos de métodos não podem receber um behavior, ou funcionam de outro jeito quando recebem. A lista completa, com os motivos, está em Limitações e atualização. Em resumo:
- Retorno por referência. Um método ou função declarado como
function &name()não pode ser interceptado; compilá-lo falha com umaWeavingException. Exclua esses métodos de uma regra ampla com&& !matchReturningByReference(). - Métodos de trait com
#[\Override]. Um método que uma classe importa de uma trait e que tem#[\Override]não pode ser interceptado nessa classe; compilá-lo falha com umaWeavingException. Exclua-o com&& !matchInherited()ou anexe o behavior à própria trait, por exemploexecution(public HelloTrait->hello(*)), que vale em toda classe que usa a trait. - Generators. Num método que contém
yield, o behavior roda quando o método é chamado, eproceed()retorna o objetoGenerator. O behavior não vê os valores produzidos peloyield. - Argumentos.
getArguments()lista os argumentos por posição. Um parâmetro variádico por referência (&...$values) é passado ao método original por valor. #[\SensitiveParameter]. Dois frames internos entre o call context e o método original ainda guardam o array de argumentos emThrowable::getTrace(). Comzend.exception_ignore_args=On, o padrão de produção, nenhum frame tem argumentos.- Propriedades. Propriedades estáticas, readonly e que já têm hooks não são interceptadas, nem propriedades
finalherdadas ouprivateherdadas.
© 2026 Alexander Lisachenko
