Behaviors y matching rules
La referencia completa para escribir behaviors, el middleware dinámico que el framework ejecuta alrededor de tu código, y las matching rules que indican dónde se aplican.
Traducido del inglés. La página en inglés es la referencia. Leer el original
Esta página cubre todo lo que escribes cuando trabajas con el framework: las behavior classes (clases de comportamiento), los behaviors (comportamientos) que contienen y que se ejecutan como middleware dinámico alrededor de tu código, el call context (contexto de llamada) que recibe cada behavior y las matching rules (reglas de coincidencia) que seleccionan dónde se ejecuta. Si todavía no has configurado un kernel, empieza por Primeros pasos. Para ver recorridos completos, del problema al código que funciona, consulta el behavior de caché y el behavior de logging.
Términos de esta página
Sección titulada «Términos de esta página»La API del framework conserva los nombres clásicos, así que te los encontrarás en el código, en los nombres de clase y en los mensajes de error. Esta documentación usa las palabras cotidianas y nombra el término de la API una sola vez:
| En esta documentación | En la API | Qué es |
|---|---|---|
| Behavior class (clase de comportamiento) | Aspect (aspecto) | Una clase que implementa Go\Aop\Aspect y agrupa behaviors relacionados |
| Behavior (comportamiento; middleware) | Advice (consejo) | Un método público de la behavior class con un atributo de Go\Lang\Attribute: #[Before], #[After], #[AfterThrowing] o #[Around] |
| Matching rule (regla de coincidencia) | Pointcut (punto de corte) | La expresión de ese atributo que selecciona dónde se ejecuta el behavior |
| Call context (contexto de llamada) | Joinpoint (punto de unión) | El momento interceptado (una llamada a un método, un acceso a una propiedad, la creación de un objeto), que se pasa al behavior como objeto |
| Compile step (paso de compilación) | Weaving (entretejido) | Convertir tus clases en los archivos que carga PHP, con los behaviors adjuntos |
| Class extension (extensión de clase) | Introduction (introducción) | Una interfaz y un trait añadidos a clases existentes |
Behavior classes
Sección titulada «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()); }}Una behavior class es una clase PHP normal que implementa Go\Aop\Aspect. Contiene lógica como logging, caché, comprobaciones de seguridad o transacciones que, de otro modo, acabaría copiada en muchas clases. Cada uno de sus behaviors se ejecuta como middleware alrededor del código que selecciona su matching rule: measure(), arriba, envuelve todos los métodos públicos de App\Service, y logFailure() se ejecuta cuando uno de ellos lanza una excepción. Como es una clase corriente, puedes usar inyección por constructor, estado privado, traits y todo lo demás que ofrece PHP.
Cuándo se ejecuta un behavior
Sección titulada «Cuándo se ejecuta un behavior»El atributo de un behavior indica cuándo se ejecuta respecto a la llamada interceptada.
| Atributo | Se ejecuta |
|---|---|
#[Before] |
Antes de la llamada. Puede cambiar los argumentos con setArguments(). |
#[After] |
Después de la llamada, también cuando lanza una excepción (como finally). |
#[AfterThrowing] |
Cuando la llamada lanza una excepción. Recibe la excepción como segundo argumento; después la excepción se vuelve a lanzar. |
#[Around] |
En lugar de la llamada, como hace un middleware. Decide si llama a proceed(), y su valor de retorno pasa a ser el resultado. |
Los cuatro atributos están en el namespace Go\Lang\Attribute y reciben una 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"; }}Un behavior Before se ejecuta justo antes del método original. Úsalo para validar la entrada o comprobar permisos. Para cambiar lo que recibe el método original, sustituye los 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 los argumentos por posición, así que te refieres a ellos por í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();}Un behavior After funciona como un bloque finally: se ejecuta tanto si el método retorna con normalidad como si lanza una excepción. Úsalo para liberar recursos o detener temporizadores.
AfterThrowing
Sección titulada «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());}Un behavior AfterThrowing se ejecuta solo cuando la llamada lanza una excepción, que recibe como segundo argumento. El framework vuelve a lanzar la excepción después del behavior, así que quien llama la sigue viendo. Úsalo para registrar errores o 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'); }}Un behavior Around se ejecuta en lugar de la llamada, como un middleware en una pila HTTP. Llamas a proceed() para pasar el control al código original, y lo que devuelva el behavior pasa a ser el resultado. Eso hace de Around el tipo más potente: decide si el original llega a ejecutarse, puede cambiar los argumentos antes de proceed(), puede cambiar el valor de retorno y puede capturar excepciones. Úsalo para caché, transacciones y lógica de reintentos.
Si no llamas a proceed(), el método original no se ejecuta:
#[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();}El call context
Sección titulada «El call context»Cada behavior recibe un objeto que describe la llamada interceptada: sus argumentos, el objeto sobre el que se ejecuta y proceed() para continuar. Su clase depende de lo que seleccione la matching rule.
Referencia del call context
Sección titulada «Referencia del call context»| Clase | Se recibe para | Métodos principales |
|---|---|---|
MethodInvocation |
execution() de métodos dinámicos y estáticos |
getThis(), getScope(), getMethod(), getArguments(), setArguments(), proceed() |
FunctionInvocation |
execution() de funciones con namespace |
getFunction(), getArguments(), setArguments(), proceed() |
FieldAccess |
access() de propiedades |
getThis(), getField(), getAccessType(), getValue(), getValueToSet(), proceed() |
ConstructorInvocation |
initialization() |
getConstructor(), getArguments(), getThis() (null antes de que exista el objeto), proceed() |
Todas están en Go\Aop\Intercept. Un MethodInvocation puede usarse como cadena, como hacen los ejemplos anteriores en los mensajes de log.
Tipos genéricos
Sección titulada «Tipos genéricos»Estas clases declaran tipos @template, así que PHPStan y los IDE conocen los tipos de getThis() y proceed(). Escribe los tipos concretos en el docblock de tu 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;}Aquí MethodInvocation<OrderService, Order> le indica al analizador que getThis() es un OrderService y que proceed() devuelve un Order.
Cómo los behaviors se convierten en middleware
Sección titulada «Cómo los behaviors se convierten en middleware»No hay magia detrás de adjuntar un behavior. Para cada método interceptado, el framework genera una cadena de middleware normal y corriente. Cada behavior se referencia como un closure creado con la sintaxis de first-class callable, directamente sobre la instancia de la behavior class:
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() obtiene la instancia de la behavior class del contenedor del kernel, y ->beforeMethodExecution(...) es el método de behavior que escribiste. Puedes hacer Ctrl-clic sobre él en tu IDE, poner un breakpoint dentro y recorrer paso a paso el código generado como si estuviera escrito a mano. Los call contexts se construyen en tiempo de compilación y quedan cacheados en el código generado, así que no hay reflexión ni análisis de atributos en tiempo de ejecución. Consulta Debuggable para saber más sobre el código generado.
Los behaviors registrados en el contenedor como closures sueltos, en lugar de como métodos de una behavior class, se adjuntan en su lugar mediante el accesor lazy The::advice(). Busca la entrada registrada por su identificador y la desenvuelve hasta llegar al closure original:
Interceptor::around(The::advice('advisor.Demo\Aspect\DynamicMethodsAspect->aroundMagicMethods')),Matching rules
Sección titulada «Matching rules»Una matching rule es una expresión que selecciona dónde se ejecuta un behavior: ejecuciones de métodos, accesos a propiedades, llamadas a funciones o creación de objetos. Es el argumento del atributo del behavior:
#[Before('execution(public App\Service->save(*))')]El playground te permite probar reglas sobre un archivo PHP; esta sección es la referencia completa.
Tipos de reglas
Sección titulada «Tipos de reglas»| Regla | Selecciona |
|---|---|
execution(modifiers Class->method(*)) |
La ejecución de un método dinámico |
execution(modifiers Class::method(*)) |
La ejecución de un método estático |
execution(Namespace\function(*)) |
Las llamadas a una función del sistema desde ese namespace |
access(modifiers Class->property) |
Las lecturas y escrituras de una propiedad de instancia |
within(ClassFilter) |
Todos los miembros (métodos y propiedades) de las clases que coinciden |
initialization(ClassFilter) |
La creación de objetos con new |
staticinitialization(ClassFilter) |
La primera carga de las clases que coinciden |
@execution(Attribute) |
Los métodos que llevan el atributo |
@access(Attribute) |
Las propiedades que llevan el atributo |
@within(Attribute) |
Todos los miembros de las clases que llevan el atributo |
matchInherited() |
Solo los miembros heredados de una clase padre o importados de un trait; !matchInherited() los excluye |
matchReturningByReference() |
Los métodos y funciones declarados function &name(); !matchReturningByReference() los excluye |
$this->pointcutName |
Una regla con nombre declarada con #[Pointcut] en un método de la misma behavior class |
Aspect\Class->pointcutName |
Una regla con nombre de otra behavior class |
La lista de argumentos es siempre (*): los argumentos no se comparan.
Fíjate en el separador: -> selecciona métodos dinámicos y ::, métodos estáticos.
execution(public App\Service\OrderService->place(*))execution(public App\Util\Money::format(*))Para interceptar llamadas a métodos mágicos, adjunta el behavior al propio __call:
execution(public Foo->__call(*))Nombres y comodines
Sección titulada «Nombres y comodines»| Patrón | Significado |
|---|---|
* |
Cualquier secuencia de caracteres dentro de una parte del nombre, incluida la vacía, sin cruzar nunca un \: get* (también get), *Service (también Service), App\*\Controller (exactamente un nivel de namespace en medio) |
** |
Cualquier profundidad de namespace: App\** es cualquier clase por debajo de App, **->*(*) es cualquier método |
a|b |
Alternativas dentro de una parte del nombre, p. ej. get*|is*. Se aplican a la parte en la que están escritas: App\Cart|Order es App\Cart o App\Order, nunca un Order global. Para clases de namespaces distintos, une dos reglas con || |
Foo+ |
El propio Foo, sus subclases e implementaciones, y las clases que usan el trait Foo (directamente o a través de una clase padre) |
Los nombres se comparan distinguiendo mayúsculas y minúsculas. Escribe los namespaces con una sola barra invertida; en una cadena PHP entre comillas simples no hace falta escaparla.
execution(public **->save*(*))execution(public App\Repository\*Repository->find*|get*(*))execution(public App\Contract\Cacheable+->*(*))Modificadores
Sección titulada «Modificadores»Las reglas de métodos y propiedades aceptan estos modificadores:
public,protected,privatefinal,readonly- los modificadores de visibilidad asimétrica
private(set)yprotected(set)
Combina alternativas con |:
execution(public|protected App\Service->*(*))Los modificadores separados por espacios deben estar todos presentes, y | tiene más precedencia que el espacio. final public|protected coincide con los métodos finales que son públicos o protegidos. Se admite un grupo de alternativas por patrón.
Las propiedades estáticas nunca se interceptan, ni tampoco las propiedades readonly ni las que ya tienen hooks. La sección sobre intercepción de propiedades, más abajo, enumera todos los casos; los motivos están en Limitaciones y actualización.
Tipos de retorno
Sección titulada «Tipos de retorno»Un patrón de método o función puede restringir el tipo de retorno declarado:
execution(public App\Repo->find*(*): App\Entity|null)Los tipos unión usan |, los tipos intersección &, y ?Foo equivale a Foo|null.
Combinar reglas
Sección titulada «Combinar reglas»| Operador | Significado |
|---|---|
&& |
Coinciden ambas |
|| |
Coincide cualquiera de las dos |
! |
Negación |
( ) |
Agrupación |
within(App\**) && !execution(public **->__construct(*))Comentarios
Sección titulada «Comentarios»Los comentarios empiezan con // y llegan hasta el final de la línea. Ayudan en expresiones largas de varias líneas:
#[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();}Reglas con nombre
Sección titulada «Reglas con nombre»Declara una regla una sola vez y referénciala desde varios 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 { /* ... */ }}El método #[Pointcut] tiene el cuerpo vacío; solo importa su atributo. Referéncialo como $this->humanEat desde la misma behavior class. Desde otra, usa el nombre de la clase que lo declara, por ejemplo App\Aspect\HealthyLiveAspect->humanEat.
Reglas por atributo
Sección titulada «Reglas por atributo»@execution, @access y @within seleccionan miembros por los atributos PHP que llevan. Así puedes marcar el código que debe recibir un behavior en lugar de seleccionarlo por su nombre:
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) hace lo mismo con las propiedades, y @within(Attribute) selecciona todos los miembros de las clases que llevan el atributo. Los atributos de las clases compiladas se copian al código generado con sus argumentos originales, así que leerlos en tiempo de ejecución funciona como antes. El behavior de caché construye un #[Cacheable(ttl: 600)] completo sobre esta regla.
Behaviors en propiedades
Sección titulada «Behaviors en propiedades»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();}Las reglas access(...) interceptan las lecturas y escrituras de propiedades de instancia mediante property hooks nativos de PHP 8.4 en las clases proxy generadas. El behavior recibe un FieldAccess. En una escritura, proceed() devuelve el valor que se almacena, así que un behavior Around puede cambiarlo, como hace el ejemplo.
Qué se puede interceptar:
- las propiedades declaradas en la propia clase compilada, incluidas las promovidas en el constructor (también las
final, en PHP 8.5). La asignación que hace el constructor se intercepta como una escritura. - las propiedades public y protected heredadas de clases padre
Qué se omite:
- las propiedades
static,readonlyy las que ya tienen hooks - las propiedades
finalheredadas de clases padre - las propiedades
privateheredadas
En las propiedades de tipo array, el proxy emite solo un hook &get por referencia, sin set. Así siguen siendo válidas las modificaciones indirectas como array_push($this->items, ...).
Cuando Doctrine hidrata o hace flush de una entidad, lee y escribe los valores en bruto de las propiedades, así que los behaviors de propiedades solo se ejecutan en los accesos que hace tu propio código. Consulta Integraciones para la configuración de Doctrine, y la página de la funcionalidad Property hooks para una visión general.
Class extensions
Sección titulada «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); }}Una class extension (extensión de clase) cambia las capacidades que exponen las clases existentes, mientras que un behavior cambia lo que ocurre cuando se ejecuta su código. #[DeclareParents] sobre una propiedad de la behavior class añade a las clases que coinciden una interfaz y un trait que la implementa. Aquí todas las clases de App\Model pasan a ser JsonSerializable sin editar ninguna. Esto también funciona con clases de paquetes de Composer; consulta la página de la funcionalidad Class extensions.
Behaviors en llamadas a funciones
Sección titulada «Behaviors en llamadas a funciones»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 las llamadas a file_get_contents() desde código del namespace App\Service. El behavior recibe un FunctionInvocation.
Los proxies de las funciones interceptadas se generan con declare(strict_types=1), un archivo por namespace. Los argumentos se convierten según el modo del archivo que hace la llamada antes de entrar en el proxy.
Creación de objetos
Sección titulada «Creación 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(...) en los archivos compilados. El behavior recibe un ConstructorInvocation. Su getThis() devuelve null antes de que exista el objeto.
staticinitialization(App\Model\*) se ejecuta una vez, después de cargar la clase.
Registrar behavior classes
Sección titulada «Registrar behavior classes»Las behavior classes son servicios del contenedor del kernel. Regístralas en el configureAop() de tu kernel, preferiblemente como servicios diferidos:
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 una factoría. El compile step (paso de compilación) nunca instancia las behavior classes: cada una se crea cuando uno de sus behaviors se ejecuta por primera vez, como lazy object nativo de PHP 8.4. add() registra una instancia que ya has construido.
Dependencias
Sección titulada «Dependencias»La factoría recibe el contenedor del kernel, un AspectContainer. Es un contenedor PSR-11, así que puedes obtener de él las dependencias 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)),);Los servicios del propio contenedor PSR-11 de tu aplicación quedan disponibles en cuanto lo conectas al contenedor del kernel con setDelegate(). Los bridges para Symfony, Laravel y Yii3 registran las behavior classes por ti; consulta Integraciones. Las opciones del kernel se tratan en Configuración y CLI.
Métodos heredados
Sección titulada «Métodos heredados»Un behavior se ejecuta una vez por ejecución del método, por muchas clases de la jerarquía que se compilen. Un método que una clase compilada solo hereda lo intercepta el ancestro compilado más cercano en el que la regla coincide (hasta la clase que declara el método); la subclase hereda ese método interceptado y no sobrescribe nada.
Cuando no existe ese ancestro, como ocurre con una clase padre fuera de includePaths o con una en la que la regla no coincide, la subclase intercepta ella misma el método heredado.
Para restringir una regla a los miembros que declara la propia clase, añade !matchInherited(). Excluye los miembros heredados de una clase padre y los importados de un trait.
Limitaciones
Sección titulada «Limitaciones»Algunos tipos de métodos no pueden recibir un behavior, o funcionan de otra manera cuando lo reciben. La lista completa, con los motivos, está en Limitaciones y actualización. En resumen:
- Retorno por referencia. Un método o función declarado
function &name()no se puede interceptar; compilarlo falla con unaWeavingException. Excluye esos métodos de una regla amplia con&& !matchReturningByReference(). - Métodos de trait con
#[\Override]. Un método que una clase importa de un trait y que lleva#[\Override]no se puede interceptar en esa clase; compilarlo falla con unaWeavingException. Exclúyelo con&& !matchInherited(), o adjunta el behavior al propio trait, por ejemploexecution(public HelloTrait->hello(*)), que se aplica en todas las clases que usan el trait. - Generadores. En un método que contiene
yield, el behavior se ejecuta cuando se llama al método, yproceed()devuelve el objetoGenerator. El behavior no ve los valores producidos conyield. - Argumentos.
getArguments()lista los argumentos por posición. Un parámetro variádico por referencia (&...$values) se pasa al método original por valor. #[\SensitiveParameter]. Dos frames internos entre el call context y el método original siguen guardando el array de argumentos enThrowable::getTrace(). Conzend.exception_ignore_args=On, el valor por defecto en producción, ningún frame tiene argumentos.- Propiedades. No se interceptan las propiedades estáticas, readonly ni las que ya tienen hooks, ni tampoco las
finalheredadas ni lasprivateheredadas.
© 2026 Alexander Lisachenko
