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»Métodos que devuelven por referencia
Sección titulada «Métodos que devuelven por referencia»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.
Métodos de trait con #[\Override]
Sección titulada «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. 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.
Generadores
Sección titulada «Generadores»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.
Parámetros variádicos por referencia
Sección titulada «Parámetros variádicos por referencia»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 constructoresforward_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.
strict_types de los proxies de funciones
Sección titulada «strict_types de los proxies de funciones»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.
Intercepción de propiedades
Sección titulada «Intercepción de propiedades»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.
Notas sobre PHP 8.4
Sección titulada «Notas sobre PHP 8.4»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.
Resumen de PHP 8.4
Sección titulada «Resumen de PHP 8.4»| 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 |
Notas sobre PHP 8.5
Sección titulada «Notas sobre PHP 8.5»Las notas sobre PHP 8.5 se basan en una auditoría del framework en PHP 8.5.10 y PHP 8.6.0beta2.
Lo que funciona en PHP 8.5
Sección titulada «Lo que funciona en PHP 8.5»- 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
staticcon visibilidad asimétrica (public static private(set)) funcionan en las clases compiladas. Las reglasaccess(...)nunca las seleccionan. - Resolución de
selfyparenten la reflexión. En PHP 8.5,ReflectionNamedType::getName()resuelve los tipos de retornoselfyparenta nombres de clase concretos. Los generadores de proxies leen el nodo de tipo del AST en bruto cuando está disponible, así que las palabras claveselfyparentse conservan en los proxies generados.
new en inicializadores no se intercepta
Sección titulada «new en inicializadores no se intercepta»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.
Resumen de PHP 8.5
Sección titulada «Resumen de PHP 8.5»| 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.
Los argumentos no se pueden seleccionar
Sección titulada «Los argumentos no se pueden seleccionar»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.
El modo debug es para desarrollo
Sección titulada «El modo debug es para desarrollo»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.
Actualizar de 3.x a 4.0
Sección titulada «Actualizar de 3.x a 4.0»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.
Lista de comprobación rápida
Sección titulada «Lista de comprobación rápida»-
Ejecuta en PHP 8.4 o posterior y actualiza las dependencias (consulta Requisitos y dependencias más abajo).
-
Haz
publiccada método de behavior de tus behavior classes (consulta Behavior classes más abajo). -
Registra las behavior classes con
add()oaddLazyService()en lugar deregisterAspect(). -
Sustituye los comodines
?de las matching rules por*, y reescribe las reglasdynamic(...). -
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 -
Si usas el bridge de Doctrine, cambia el descubrimiento de entidades a
WovenEntityClassLocator.
Requisitos y dependencias
Sección titulada «Requisitos y dependencias»- PHP 8.4+ con
ext-tokenizer. - Actualiza las dependencias con Composer. Las versiones requeridas figuran en
composer.json. psr/containeres una dependencia nueva, ynikic/php-parserse instala a través degoaop/parser-reflection.laminas/laminas-codeya no se usa. Los proxies los genera el paquete internoGo\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/aspectnecesitasymfony/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
_proxiesya 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.cacheasocia 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 (onullsi no está transformado) para los includes que interceptaINTERCEPT_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.phpse cachea como{cacheDir}/src/Aspect/LoggingAspect.cache.php. Los interceptores ya no son serializables: se eliminanAbstractInterceptor::__serialize(),__unserialize(),serializeAdvice()yunserializeAdvice().
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.
Behavior classes
Sección titulada «Behavior classes»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.
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}Un atributo de behavior por método
Sección titulada «Un atributo de behavior por método»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.
Registrar behavior classes
Sección titulada «Registrar behavior classes»Se elimina AspectContainer::registerAspect(). Las behavior classes son servicios normales del contenedor.
Antes, en 3.x:
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}Después, en 4.0:
// 4.0protected 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.
Contenedor PSR-11
Sección titulada «Contenedor PSR-11»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 llamarseget().has()viene de la interfaz PSR, con la misma firma.- Un
containerClasspersonalizado implementaget()en lugar degetValue(), además desetDelegate(), que conecta el contenedor de tu aplicación. Consulta Configuración y CLI.
// 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.
API de Advice y de los interceptores
Sección titulada «API de Advice y de los interceptores»- Se eliminan las interfaces marcadoras
AdviceBefore,AdviceAfteryAdviceAround.AdviceexigegetType(): AdviceTypeEnum, con los casosBefore,After,AfterThrowing,AroundeIntroduction. - Los constructores de las invocaciones (
DynamicTraitAliasMethodInvocation,StaticTraitAliasMethodInvocation,ReflectionFunctionInvocation) exigen unClosure $closureToCallno nullable. - Se elimina
DeclareError: el atributo,DeclareErrorInterceptoryPointcutBuilder::declareError(). En su lugar, emite avisos o lanza excepciones desde un behavior#[Before]o#[Around].
Matching rules
Sección titulada «Matching rules»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.
Se elimina el comodín ?
Sección titulada «Se elimina el comodín ?»? 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 dynamic(...)
Sección titulada «Se elimina dynamic(...)»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:
#[Around('dynamic(public Foo->save*(*))')]Después, en 4.0:
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}Matching rules que han cambiado
Sección titulada «Matching rules que han cambiado»- Precedencia de los modificadores. Los modificadores separados por espacios deben estar todos presentes, y
|tiene mayor precedencia.final public|protectedsignifica final Y (public O protected). En 3.x también seleccionaba todos los métodos públicos no finales. Foo+incluyeFoo. Ahora también selecciona la propia clase o interfazFoo, y las clases que usan el traitFoo. 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 extiendenAttr. *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 claseSensor, yset*omitía un método llamadoset(). 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|BseleccionaNs\AyNs\B. En 3.x significabaNs\Ao la clase globalB. 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->*(*)). ModifierPointcutes final e inmutable. Las máscaras son argumentos del constructor, yandMatch(),orMatch()ynotMatch()devuelven una instancia nueva.
Compilador y código generado
Sección titulada «Compilador y código generado»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 comprobacionesinstanceofven el padre original. - Se elimina
AspectContainer::AOP_PROXIED_SUFFIX. UsaORIGINAL_TRAIT_SUFFIX('OriginalTrait') oORIGINAL_TRAIT_FILE_SUFFIX('OriginalTrait.php'). AbstractMethodInvocation::TRAIT_ALIAS_PREFIXse sustituye porTRAIT_ALIAS_SUFFIX('OriginalAlias').- Los hooks de
InitializationAwareyStaticInitializationAwarese llaman__initialization()y__staticInitialization(). self::en el código generado se resuelve a la clase proxy, así que se eliminanSelfValueTransformerySelfValueVisitor.Go\Aop\Featureses una clase final en lugar de una interfaz. Las constantes no cambian, pero ya no se puede implementar.Features::ALLcombina todos los flags, yAspectKernel::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.
API sin uso eliminada
Sección titulada «API sin uso eliminada»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 implementanGo\Aop\Aspect. Quita el atributo de tus behavior classes. Pointcut::KIND_TRAIT.Pointcut::KIND_ALLvale119en lugar de127.Go\Proxy\Part\InterceptedConstructorGeneratoryGo\Proxy\Part\FunctionParameterList.InterceptedMethodGenerator::getBody()ysetBody(),CachePathManager::setCacheDir()yAopComposerLoader::wasInitialized().AopComposerLoader::init()devuelve el mismo flag.- La entrada de contenedor
'kernel.options'. UsaAspectKernel::getOptions().
Enums y constantes renombrados
Sección titulada «Enums y constantes renombrados»| 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) {Kernel y transformadores
Sección titulada «Kernel y transformadores»AspectKernel::registerTransformers(), que devolvía instancias de transformadores, se sustituye porregisterTransformerServices(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, ...)desdeconfigureAop().- Se elimina
CachingTransformer: la decisión sobre la caché vive enSourceTransformingLoader. Se eliminaSourceTransformingLoader::addTransformer(), ytransformCode()devuelve elTransformerResultglobal. StreamMetaData::$sourcees de solo lectura: se reconstruye a partir de$tokenStreamen cada lectura. Los transformadores personalizados editan los tokens de$tokenStream, o los sustituyen consetTokenStreamFromRawTokens().ConstructorExecutionTransformer,FilterInjectorTransformeryMagicConstantTransformerya no sonSourceTransformer. Son reglasNodeRewriter, que aplica un único recorrido deSyntaxTreeRewritersobre el árbol sintáctico. Ese recorrido es un servicio del framework: abre la cadena antes deWeavingTransformer, incluso cuando se sobrescriberegisterTransformerServices().- Los
SourceTransformerpersonalizados se registran como antes. Para reescribir nodos sueltos, registra un servicioNodeRewriteren lugar de un transformador que recorra el árbol por su cuenta. Consulta Configuración y CLI para ampliar el pipeline de transformación.
Clases finales e internas
Sección titulada «Clases finales e internas»Las clases que nunca se pensaron para extenderse ahora son final:
Go\Core\Container,Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\Instrument\ClassLoading\AopComposerLoader,SourceTransformingLoader,Go\Instrument\PathResolver- los transformadores
WeavingTransformer,FilterInjectorTransformer,MagicConstantTransformeryStreamMetaData - los generadores de proxies
EnumProxyGenerator,TraitProxyGeneratoryFunctionProxyGenerator - 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().
Excepciones
Sección titulada «Excepciones»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.
Bridge de Doctrine
Sección titulada «Bridge de Doctrine»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());Consola
Sección titulada «Consola»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:weavingdevolví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:aopfalla 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-fastpara detenerte en el primer error:
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast© 2026 Alexander Lisachenko
