Ir al contenido
Documentación

Limitaciones y actualización a 4.0

Lo que la versión 4.0 no puede interceptar y cómo sortearlo, seguido de la guía de migración completa desde 3.x.

Traducido del inglés. La página en inglés es la referencia. Leer el original

Esta página tiene dos mitades. La primera enumera lo que la versión 4.0 no intercepta, por qué, y qué hacer en su lugar. La segunda es la guía completa de migración de 3.x a 4.0, en el orden en que conviene aplicarla.

Las limitaciones se exponen tal como son. La mayoría vienen del propio PHP, y cada una falla de forma predecible: o bien el compilador lanza una WeavingException en tiempo de compilación, o bien el miembro se omite.

Métodos y funciones que no se pueden interceptar

Sección titulada «Métodos y funciones que no se pueden interceptar»

Un método o una función declarados function &name() no se pueden interceptar. Los call contexts (contextos de llamada) y los behaviors (comportamientos) devuelven valores, así que quien llama recibiría una copia en lugar de la referencia. Compilar uno de ellos falla con una WeavingException.

Excluye esos métodos de una matching rule (regla de coincidencia) amplia con !matchReturningByReference():

#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]

En 3.x el call context devolvía una copia con un notice. En 4.0 es un error, así que encuentras estos métodos en tiempo de compilación.

Un método que una clase importa de un trait y que lleva #[\Override] no se puede interceptar en esa clase. PHP copia el atributo al alias privado al que llama el proxy, y ese alias no sobrescribe nada. Compilar uno de ellos falla con una WeavingException.

Tienes cuatro opciones:

  • Excluir los métodos de traits de la regla con && !matchInherited().
  • Excluir solo ese método, por ejemplo && !execution(public Foo->hello(*)).
  • Quitar #[\Override] del trait.
  • Apuntar al propio trait, por ejemplo execution(public HelloTrait->hello(*)). Se compila el trait, lo que funciona con #[\Override], y el behavior se aplica en todas las clases que usan el trait.

Los métodos de traits que una clase hereda de su clase padre no se ven afectados.

En un método que contiene yield, el behavior se ejecuta cuando se llama al método, y proceed() devuelve el objeto Generator. El behavior no ve los valores producidos con yield: se generan más tarde, mientras quien llama itera.

getArguments() lista los argumentos por posición. Un parámetro variádico por referencia (&...$values) se pasa al método original por valor.

#[\SensitiveParameter] en las trazas de pila

Sección titulada «#[\SensitiveParameter] en las trazas de pila»

El proxy conserva el atributo. Los frames del framework que llevan los argumentos como array los ocultan: el __invoke() del call context, el __initialization() generado y el new reescrito.

Dos funciones internas entre el call context y el método original no pueden ocultarlos:

  • ReflectionMethod::invokeArgs(), para métodos de instancia y constructores
  • forward_static_call_array(), para métodos estáticos

Sus frames en Throwable::getTrace() siguen conteniendo el array de argumentos, que la forma textual de la traza imprime como Array. Los rastreadores de errores que recogen los argumentos de los frames lo ven. Con zend.exception_ignore_args=On, el valor por defecto en producción, ningún frame tiene argumentos.

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 llama antes de entrar en el proxy.

Las reglas access(...) interceptan las lecturas y escrituras de propiedades de instancia mediante property hooks nativos de PHP 8.4 en el proxy generado: los hooks generados encaminan las lecturas y escrituras a través de call contexts ClassFieldAccess. Consulta property interception para ver lo que esto te aporta. Las siguientes propiedades se omiten de forma intencionada:

Propiedad Por qué
Propiedades static PHP no tiene property hooks para propiedades estáticas. Es una restricción del motor.
Propiedades readonly, incluidas public private(set) readonly PHP no permite hooks en propiedades readonly.
Propiedades que ya tienen hooks get o set El framework no puede combinar sus hooks con los que tú definiste.
Propiedades final heredadas de clases padre No soportado.
Propiedades private heredadas No soportado.

Los objetivos soportados son las propiedades declaradas en la propia clase compilada, incluidas las propiedades promovidas en el constructor, y las propiedades public y protected heredadas de clases padre.

Una propiedad omitida no genera ningún error. Si tu regla la selecciona, la propiedad queda fuera de la intercepción sin aviso: AdviceMatcher omite las propiedades estáticas, readonly y con hooks antes de generar ningún código de proxy. Además, como red de seguridad, el generador de propiedades rechaza una propiedad así con una WeavingException.

La visibilidad asimétrica en propiedades que no son readonly se conserva. public protected(set) string $name mantiene sus modificadores en la clase proxy.

El framework construye la intercepción de propiedades sobre los property hooks de PHP 8.4, y su contenedor usa los lazy objects de PHP 8.4 para los servicios diferidos. Dos partes de esto tienen límites.

La inicialización de lazy objects no se puede interceptar

Sección titulada «La inicialización de lazy objects no se puede interceptar»

PHP 8.4 introdujo ReflectionClass::newLazyProxy() y ReflectionClass::newLazyGhost() para la inicialización lazy de objetos. El Container del framework usa lazy proxies nativos para sus propios servicios diferidos y para las behavior classes (clases de comportamiento) registradas por nombre de clase. Al obtener uno de esos servicios se entrega una instancia newLazyProxy() tipada y correcta frente a instanceof. La factoría registrada solo se ejecuta en la primera interacción real con ese objeto.

Las clases que PHP no puede hacer lazy recurren a la construcción inmediata: las clases internas y sus subclases que no son stdClass, las clases abstractas y los enums.

No hay call context para el momento en que un lazy proxy materializa su instancia subyacente, así que la propia inicialización de lazy objects no se puede interceptar.

Funcionalidad de PHP 8.4 Soporte Notas
Property hooks en propiedades nuevas Generados por el framework Se usan para la intercepción access(...)
Propiedades con hooks existentes Se omiten El framework no puede combinarse con hooks definidos por el usuario
Propiedades readonly Se omiten No se permiten hooks en propiedades readonly
Visibilidad asimétrica (no readonly) Se conserva Los modificadores de visibilidad se copian al proxy
Atributo #[\Deprecated] Se propaga Se copia a los métodos y clases del proxy
Lazy objects (newLazyProxy) No interceptables No hay call context para la inicialización lazy

Las notas sobre PHP 8.5 se basan en una auditoría del framework en PHP 8.5.10 y PHP 8.6.0beta2.

  • Operador pipe |>. Funciona dentro de los cuerpos de los métodos compilados. Los cuerpos de los métodos se trasladan literalmente al trait de cuerpo <Class>OriginalTrait, así que cualquier sintaxis de expresiones de PHP 8.5 que contengan se conserva.
  • clone with. Las expresiones en el código compilado funcionan como se espera.
  • #[\NoDiscard]. El atributo se copia al método proxy generado, y el call context devuelve el valor del método interceptado. El aviso del motor “return value not used” se sigue emitiendo para los métodos compilados.
  • Atributos en constantes de clase, incluido #[\Deprecated]. Las constantes de clase permanecen en el trait generado junto con sus atributos.
  • Closures y first-class callables como valores por defecto de parámetros. Sobreviven a la compilación en las firmas de los métodos proxy.
  • Visibilidad asimétrica estática. Las propiedades static con visibilidad asimétrica (public static private(set)) funcionan en las clases compiladas. Las reglas access(...) nunca las seleccionan.
  • Resolución de self y parent en la reflexión. En PHP 8.5, ReflectionNamedType::getName() resuelve los tipos de retorno self y parent a nombres de clase concretos. Los generadores de proxies leen el nodo de tipo del AST en bruto cuando está disponible, así que las palabras clave self y parent se conservan en los proxies generados.

Una expresión new dentro de una expresión constante la evalúa el motor. Eso abarca el valor por defecto de un parámetro o de un parámetro promovido del constructor, el inicializador de una variable estática y el argumento de un atributo. El compilador deja estas expresiones como están, así que el código funciona, pero un behavior initialization(...) no se ejecuta para los objetos que crean. Solo se interceptan las expresiones new en código ejecutable.

Las propiedades estáticas nunca son interceptables

Sección titulada «Las propiedades estáticas nunca son interceptables»

Las propiedades estáticas, incluidas las propiedades static de PHP 8.5 con visibilidad asimétrica, no se pueden interceptar con reglas access(...). Los property hooks de PHP no existen para propiedades estáticas, así que el framework no tiene ningún mecanismo de intercepción para ellas, y AdviceMatcher las excluye de la intercepción de propiedades. Es una restricción del motor de PHP, no un bug.

Funcionalidad de PHP 8.5 Soporte Notas
Operador pipe |> en cuerpos de métodos Funciona Los cuerpos se trasladan literalmente al trait generado
clone with Funciona
#[\NoDiscard] Se propaga Se copia al proxy; el call context devuelve el valor
Atributos en constantes de clase (incluido #[\Deprecated]) Se conservan Las constantes permanecen en el trait generado
Closures y first-class callables como valores por defecto de parámetros Funciona
Visibilidad asimétrica estática (sin interceptar) Se conserva Las propiedades estáticas nunca son interceptables con access()
Resolución de self/parent en la reflexión Resuelta La generación de proxies usa los nodos de tipo del AST en bruto
new en inicializadores No se intercepta Lo evalúa el motor; los behaviors initialization(...) no se ejecutan para él
Intercepción de propiedades estáticas con access() Nunca No hay property hooks para propiedades estáticas (restricción del motor de PHP)

Alcance de la compilación y límites de las matching rules

Sección titulada «Alcance de la compilación y límites de las matching rules»

Clases cargadas antes de que arranque el kernel

Sección titulada «Clases cargadas antes de que arranque el kernel»

Solo se compilan las clases cargadas después de inicializar el kernel. Una clase que se carga antes de ese momento se ejecuta sin sus behaviors. Inicializa el kernel lo antes posible en tu controlador frontal. Los bridges de los frameworks deben arrancar primero; consulta Integraciones para ver cómo lo resuelve cada bridge.

La lista de argumentos de una matching rule es siempre (*). Una regla selecciona métodos por clase, nombre, modificadores, tipo de retorno y atributos, nunca por los valores de los argumentos ni por los tipos de los parámetros. Para actuar sobre argumentos concretos, selecciona el método e inspecciona $invocation->getArguments() dentro del behavior. La sintaxis completa está en Behaviors y matching rules.

Costes en tiempo de ejecución que conviene conocer

Sección titulada «Costes en tiempo de ejecución que conviene conocer»

Estas cifras proceden del benchmark del propio framework en docs/performance.md: una pequeña aplicación de tienda con unos 250 archivos, 94 clases compiladas y 6 behavior classes, en PHP 8.5.12 con el JIT desactivado. El archivo explica cómo se midieron y cómo reproducirlas.

Las reglas initialization() afectan a cada new

Sección titulada «Las reglas initialization() afectan a cada new»

Mientras haya registrada una regla initialization, cada new de los archivos generados pasa por el transformador. Una clase sin behaviors de inicialización (y con un constructor público) se sigue creando con un new nativo, que cuesta unos 130 ns más que un new normal. Una clase con behaviors de inicialización pasa por el call context completo. Prefiere las reglas de métodos cuando cumplen su función.

Con 'debug' => true, las clases generadas se sirven a través del stream filter, de modo que los breakpoints de Xdebug y las constantes mágicas apuntan a tus archivos originales, y los archivos modificados se recompilan automáticamente. En el benchmark, las peticiones hot (calientes) en modo debug tardan más del doble que en modo producción. Usa 'debug' => false en producción; consulta Producción y rendimiento.

La versión 4.0 sustituye el compilador basado en herencia por uno basado en traits, genera los behaviors como first-class callables y reconstruye las cachés para PHP 8.4. La mayoría de las aplicaciones solo necesitan la lista de comprobación de abajo. Las secciones que la siguen describen cada cambio incompatible. Los nombres de la API que aparecen en ellas mantienen los términos clásicos; la tabla de términos los relaciona con las palabras que se usan aquí. La lista completa de cambios está en el CHANGELOG.

  1. Ejecuta en PHP 8.4 o posterior y actualiza las dependencias (consulta Requisitos y dependencias más abajo).

  2. Haz public cada método de behavior de tus behavior classes (consulta Behavior classes más abajo).

  3. Registra las behavior classes con add() o addLazyService() en lugar de registerAspect().

  4. Sustituye los comodines ? de las matching rules por *, y reescribe las reglas dynamic(...).

  5. Borra el directorio de la caché y vuelve a precalentarla. El argumento es el archivo que inicializa tu kernel:

    Ventana de terminal
    vendor/bin/aspect cache:warmup:aop public/index.php
  6. Si usas el bridge de Doctrine, cambia el descubrimiento de entidades a WovenEntityClassLocator.

  • PHP 8.4+ con ext-tokenizer.
  • Actualiza las dependencias con Composer. Las versiones requeridas figuran en composer.json.
  • psr/container es una dependencia nueva, y nikic/php-parser se instala a través de goaop/parser-reflection.
  • laminas/laminas-code ya no se usa. Los proxies los genera el paquete interno Go\Proxy\Generator. El código que extendía los generadores del framework, o que dependía de las clases generadoras de laminas que venían con el framework, tiene que actualizarse.
  • bin/aspect necesita symfony/console.

Todos los formatos de caché han cambiado, y no se reutiliza ningún archivo de caché de 3.x.

  • Estructura de los proxies. El subdirectorio _proxies ya no existe. Un proxy se guarda en la ruta relativa de su archivo fuente bajo el directorio de la caché, y el código fuente generado (el cuerpo original de la clase como trait <Class>OriginalTrait) junto a él.
  • Class map. _include.cache asocia cada clase compilada con su archivo cacheado y se entrega a Composer en el arranque. También asocia cada archivo fuente conocido con su archivo cacheado (o null si no está transformado) para los includes que intercepta INTERCEPT_INCLUDES. Un directorio de caché sin él se considera obsoleto.
  • Caché de las behavior classes. Los blobs serializados {cacheDir}/_aspect/sha1(FQCN) se sustituyen por archivos PHP normales junto a los fuentes generados: {appDir}/src/Aspect/LoggingAspect.php se cachea como {cacheDir}/src/Aspect/LoggingAspect.cache.php. Los interceptores ya no son serializables: se eliminan AbstractInterceptor::__serialize(), __unserialize(), serializeAdvice() y unserializeAdvice().

Los archivos de metadatos llevan una versión de formato. Con Features::PREBUILT_CACHE, una caché construida por otra versión del framework se rechaza con una excepción en lugar de reconstruirse en tiempo de ejecución.

Features::PREBUILT_CACHE ahora confía por completo en la caché. Se omiten todas estas comprobaciones: las del directorio y de permisos de escritura, las comparaciones de filemtime, las de recursos vigilados y las de vigencia de las cachés de las behavior classes. Reconstruir la caché en el despliegue es responsabilidad de quien despliega.

La opción cacheFileMode se valida. Debe ser un entero entre 0600 y 0777 que conceda al propietario permisos de lectura y escritura. Los directorios reciben permisos de búsqueda acordes con los bits de lectura del modo.

Los métodos de behavior deben ser públicos

Sección titulada «Los métodos de behavior deben ser públicos»

Los proxies generados llaman a los behaviors como first-class callables sobre la instancia de la behavior class. Por eso, un método con #[Before], #[After], #[Around] o #[AfterThrowing] debe ser public. El loader lanza una AspectException para los métodos de behavior protegidos o privados. Los métodos que solo llevan #[Pointcut] pueden tener cualquier visibilidad.

3.x
#[Before('execution(public Example->*(*))')]
protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0
#[Before('execution(public Example->*(*))')]
public function beforeMethod(MethodInvocation $invocation): void {}

Un método de una behavior class lleva como máximo uno de #[Before], #[After], #[Around] y #[AfterThrowing]. Un segundo lanza una AspectException. Divide un método así en un método por behavior. #[Pointcut] se puede seguir combinando con un atributo de behavior en el mismo método, y los atributos que no pertenecen al framework se ignoran.

Se elimina AspectContainer::registerAspect(). Las behavior classes son servicios normales del contenedor.

Antes, en 3.x:

app/ApplicationAspectKernel.php
// 3.x
protected function configureAop(AspectContainer $container)
{
$container->registerAspect(new MonitorAspect());
}

Después, en 4.0:

app/ApplicationAspectKernel.php
// 4.0
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed when one of its behaviors runs for the first time
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative
// $container->add(MonitorAspect::class, new MonitorAspect());
}

addLazyService() guarda una factoría y construye el servicio la primera vez que se obtiene. El código que esperaba que existiera una instancia de lazy proxy en el arranque debe llamar a getService(). Una factoría que devuelve un objeto del tipo incorrecto falla ahora en el primer uso, no en el registro.

AspectContainer::addResource() forma parte de la interfaz. onRegistration() te permite reaccionar a los registros diferidos de servicios que implementan una interfaz.

AspectContainer extiende Psr\Container\ContainerInterface, así que puedes pasar el contenedor a cualquier código que espere un contenedor PSR-11.

  • AspectContainer::getValue() pasa a llamarse get().
  • has() viene de la interfaz PSR, con la misma firma.
  • Un containerClass personalizado implementa get() en lugar de getValue(), además de setDelegate(), que conecta el contenedor de tu aplicación. Consulta Configuración y CLI.
4.0
// before
$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');

Un id desconocido lanza ServiceNotFoundException, que implementa Psr\Container\NotFoundExceptionInterface. getService() lanza Go\Aop\Exception\ContainerException cuando la entrada no es una instancia de la clase solicitada. Esa excepción es una InvalidConfigurationException que implementa Psr\Container\ContainerExceptionInterface.

El cambio de nombre se aplica solo al contenedor. FieldAccess::getValue() en los call contexts de propiedades no cambia.

  • Se eliminan las interfaces marcadoras AdviceBefore, AdviceAfter y AdviceAround. Advice exige getType(): AdviceTypeEnum, con los casos Before, After, AfterThrowing, Around e Introduction.
  • Los constructores de las invocaciones (DynamicTraitAliasMethodInvocation, StaticTraitAliasMethodInvocation, ReflectionFunctionInvocation) exigen un Closure $closureToCall no nullable.
  • Se elimina DeclareError: el atributo, DeclareErrorInterceptor y PointcutBuilder::declareError(). En su lugar, emite avisos o lanza excepciones desde un behavior #[Before] o #[Around].

Se rechazan los métodos que devuelven por referencia

Sección titulada «Se rechazan los métodos que devuelven por referencia»

Compilar un método o una función declarados function &name() falla con una WeavingException, porque el call context devolvería una copia en lugar de la referencia. 3.x devolvía una copia con un notice. Añade && !matchReturningByReference() a las reglas que seleccionan esos métodos.

? en los patrones de nombres y tipos ya no es un comodín de un solo carácter, porque chocaba con los tipos nullable. En los patrones de tipo de retorno, un ? inicial es un marcador de nullable: ?Foo equivale a Foo|null. Sustituye los comodines ? por *.

Se elimina la regla dynamic(...), junto con MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC y los parámetros $instanceOrScope y $arguments de Pointcut::matches(). Intercepta el propio método mágico y lee el nombre invocado de los argumentos.

Antes, en 3.x:

3.x
#[Around('dynamic(public Foo->save*(*))')]

Después, en 4.0:

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • Precedencia de los modificadores. Los modificadores separados por espacios deben estar todos presentes, y | tiene mayor precedencia. final public|protected significa final Y (public O protected). En 3.x también seleccionaba todos los métodos públicos no finales.
  • Foo+ incluye Foo. Ahora también selecciona la propia clase o interfaz Foo, y las clases que usan el trait Foo. Añade && !within(Foo) para excluir el propio tipo.
  • Las reglas de atributos seleccionan subclases. @execution(Attr) y las demás reglas de atributos también seleccionan los atributos que extienden Attr.
  • * también coincide con nada. En los patrones de nombres y de tipos de retorno, * representa cualquier secuencia de caracteres dentro de una parte del nombre, incluida la vacía. En 3.x necesitaba al menos un carácter: Sensor* omitía la propia clase Sensor, y set* omitía un método llamado set(). Ahora esas reglas también los seleccionan. Exclúyelos con && !execution(public Foo->set(*)) o && !within(Foo) si hace falta.
  • Las alternativas con | se quedan dentro de su parte del nombre. Ns\A|B selecciona Ns\A y Ns\B. En 3.x significaba Ns\A o la clase global B. Un patrón que enumeraba clases de namespaces distintos (Foo\A|Bar\B) tiene que escribirse como dos reglas: execution(public Foo\A->*(*)) || execution(public Bar\B->*(*)).
  • ModifierPointcut es final e inmutable. Las máscaras son argumentos del constructor, y andMatch(), orMatch() y notMatch() devuelven una instancia nueva.

El cuerpo original de la clase se convierte en un trait, <Class>OriginalTrait. La clase proxy conserva el nombre, el padre y las interfaces originales, y usa ese trait con alias privados <method>OriginalAlias. En 3.x el proxy extendía una clase padre renombrada <Class>__AopProxied. Esto afecta al código que dependía de esa capa de herencia:

  • El proxy ya no tiene una clase padre renombrada. get_parent_class(), parent:: dentro de la clase y las comprobaciones instanceof ven el padre original.
  • Se elimina AspectContainer::AOP_PROXIED_SUFFIX. Usa ORIGINAL_TRAIT_SUFFIX ('OriginalTrait') o ORIGINAL_TRAIT_FILE_SUFFIX ('OriginalTrait.php').
  • AbstractMethodInvocation::TRAIT_ALIAS_PREFIX se sustituye por TRAIT_ALIAS_SUFFIX ('OriginalAlias').
  • Los hooks de InitializationAware y StaticInitializationAware se llaman __initialization() y __staticInitialization().
  • self:: en el código generado se resuelve a la clase proxy, así que se eliminan SelfValueTransformer y SelfValueVisitor.
  • Go\Aop\Features es una clase final en lugar de una interfaz. Las constantes no cambian, pero ya no se puede implementar. Features::ALL combina todos los flags, y AspectKernel::hasFeature() lanza una excepción ante un flag desconocido.
  • Se elimina Features::PARAMETER_WIDENING. Borra el flag de las opciones de tu kernel si lo pasabas.

Estas clases, métodos y constantes públicos no tenían uso dentro del framework y se eliminan:

  • El atributo #[Aspect] (Go\Lang\Attribute\Aspect). El framework nunca lo leía: las behavior classes se identifican porque implementan Go\Aop\Aspect. Quita el atributo de tus behavior classes.
  • Pointcut::KIND_TRAIT. Pointcut::KIND_ALL vale 119 en lugar de 127.
  • Go\Proxy\Part\InterceptedConstructorGenerator y Go\Proxy\Part\FunctionParameterList.
  • InterceptedMethodGenerator::getBody() y setBody(), CachePathManager::setCacheDir() y AopComposerLoader::wasInitialized(). AopComposerLoader::init() devuelve el mismo flag.
  • La entrada de contenedor 'kernel.options'. Usa AspectKernel::getOptions().
3.x / desarrollo previo de 4.0 4.0
TransformerResultEnum::RESULT_TRANSFORMED TransformerResult::Transformed
TransformerResultEnum::RESULT_ABSTAIN TransformerResult::Abstain
TransformerResultEnum::RESULT_ABORTED TransformerResult::Aborted
FieldAccessType::READ / WRITE FieldAccessType::Read / Write
AspectContainer::AOP_PROXIED_SUFFIX AspectContainer::ORIGINAL_TRAIT_SUFFIX
AspectContainer::getValue() AspectContainer::get() (PSR-11)

Los enums de Go\Proxy\Generator (Visibility, PropertyModifier, ClassModifier) también usan casos en PascalCase. Los transformadores de código fuente personalizados devuelven casos de TransformerResult, y los behaviors que comparan getAccessType() usan los nuevos nombres de los casos:

if ($access->getAccessType() === FieldAccessType::WRITE) {
if ($access->getAccessType() === FieldAccessType::Write) {
  • AspectKernel::registerTransformers(), que devolvía instancias de transformadores, se sustituye por registerTransformerServices(AspectContainer $container), que registra servicios diferidos del contenedor. Sobrescríbelo para sustituir, omitir, reordenar o ampliar los transformadores incorporados. Para añadir uno al final, llama a $container->addLazyService(MyTransformer::class, ...) desde configureAop().
  • Se elimina CachingTransformer: la decisión sobre la caché vive en SourceTransformingLoader. Se elimina SourceTransformingLoader::addTransformer(), y transformCode() devuelve el TransformerResult global.
  • StreamMetaData::$source es de solo lectura: se reconstruye a partir de $tokenStream en cada lectura. Los transformadores personalizados editan los tokens de $tokenStream, o los sustituyen con setTokenStreamFromRawTokens().
  • ConstructorExecutionTransformer, FilterInjectorTransformer y MagicConstantTransformer ya no son SourceTransformer. Son reglas NodeRewriter, que aplica un único recorrido de SyntaxTreeRewriter sobre el árbol sintáctico. Ese recorrido es un servicio del framework: abre la cadena antes de WeavingTransformer, incluso cuando se sobrescribe registerTransformerServices().
  • Los SourceTransformer personalizados se registran como antes. Para reescribir nodos sueltos, registra un servicio NodeRewriter en lugar de un transformador que recorra el árbol por su cuenta. Consulta Configuración y CLI para ampliar el pipeline de transformación.

Las clases que nunca se pensaron para extenderse ahora son final:

  • Go\Core\Container, Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\Instrument\ClassLoading\AopComposerLoader, SourceTransformingLoader, Go\Instrument\PathResolver
  • los transformadores WeavingTransformer, FilterInjectorTransformer, MagicConstantTransformer y StreamMetaData
  • los generadores de proxies EnumProxyGenerator, TraitProxyGenerator y FunctionProxyGenerator
  • los atributos #[Before], #[After], #[Around], #[AfterThrowing], #[Pointcut] y #[DeclareParents]

Go\Lang\Attribute\AbstractInterceptor es abstract. Las clases que solo forman parte de la maquinaria del framework están marcadas como @internal y no están cubiertas por las garantías de compatibilidad hacia atrás: AdviceMatcher, AspectLoader, CachedAspectLoader, CachePathManager, CacheWarmer, Enumerator, InterceptorInjector, The y NativeLazyProxy.

Sustituye las subclases de estas clases por composición, o por tu propio contenedor o transformador registrado en configureAop() o registerTransformerServices().

Todas las excepciones que lanza el framework implementan Go\Aop\Exception\ExceptionInterface, así que un solo catch maneja cualquiera de sus fallos. Varios puntos de lanzamiento han cambiado de tipo:

Situación 3.x 4.0
Opciones del kernel, registros en el contenedor o entrada de consola no válidos RuntimeException, InvalidArgumentException, UnexpectedValueException InvalidConfigurationException (una InvalidArgumentException)
Matching rule no válida UnexpectedValueException, InvalidArgumentException PointcutSyntaxException (una AspectException)
Id de contenedor desconocido OutOfBoundsException ServiceNotFoundException (una OutOfBoundsException y una NotFoundExceptionInterface de PSR-11)
Entrada del contenedor de tipo incorrecto en getService() InvalidArgumentException ContainerException (una InvalidConfigurationException y una ContainerExceptionInterface de PSR-11)
Compilación, generación de proxies, escrituras en la caché RuntimeException, LogicException, InvalidArgumentException WeavingException (una RuntimeException)
Behavior que no se puede cachear Go\Core\Cache\NotCompilableException Go\Aop\Exception\NotCompilableException
Behavior class no válida, errores en tiempo de ejecución del call context Go\Aop\AspectException Go\Aop\Exception\AspectException, Go\Aop\Exception\InvocationException

Donde capturabas los tipos de SPL de la tabla, captura ExceptionInterface o los tipos nuevos.

El bridge ya no reescribe los metadatos de las entidades. El apaño del mapped superclass de 3.x solo se aplicaba al motor basado en herencia, y Doctrine mapea correctamente una entidad compilada tal cual. En su lugar, configura dos cosas (Doctrine ORM 3.6+):

use Doctrine\ORM\Events;
use Doctrine\ORM\Mapping\Driver\AttributeDriver;
use Go\Bridge\Doctrine\MetadataLoadInterceptor;
use Go\Bridge\Doctrine\WovenEntityClassLocator;
// Discover entities through the autoloader, which serves the generated classes
$configuration->setMetadataDriverImpl(
new AttributeDriver(WovenEntityClassLocator::createFromDirectories([__DIR__ . '/src/Entity'])),
);
// Intercepted properties become hooked properties, which Doctrine supports with native lazy objects
$configuration->enableNativeLazyObjects(true);
// Optional: reports misconfiguration early; a plain listener, no longer an EventSubscriber
$eventManager->addEventListener(Events::loadClassMetadata, new MetadataLoadInterceptor());

Los comandos declaran sus nombres con #[AsCommand] y bin/aspect los carga de forma lazy. Todos los comandos devuelven Command::SUCCESS o Command::FAILURE.

  • En 3.x, debug:weaving devolvía el número bruto de errores. Si un script dependía de ese número, comprueba el código de salida en su lugar.
  • cache:warmup:aop falla cuando un archivo no se puede compilar, así que un script de despliegue que ignoraba los errores del precalentamiento ahora se detiene ahí. Añade --fail-fast para detenerte en el primer error:
Ventana de terminal
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast

© 2026 Alexander Lisachenko