Limitações e atualização para a 4.0
O que a versão 4.0 não consegue interceptar e como contornar isso, seguido do guia completo de migração a partir da 3.x.
Traduzido do inglês. A página em inglês é a referência. Ler o original
Esta página tem duas metades. A primeira lista o que a versão 4.0 não intercepta, por quê e o que fazer no lugar. A segunda é o guia completo de migração da 3.x para a 4.0, na ordem em que você deve aplicá-lo.
As limitações são apresentadas como são. A maioria vem do próprio PHP, e cada uma falha de forma previsível: ou o compilador lança uma WeavingException em tempo de compilação, ou o membro é pulado.
Métodos e funções que não podem ser interceptados
Seção intitulada “Métodos e funções que não podem ser interceptados”Métodos que retornam por referência
Seção intitulada “Métodos que retornam por referência”Um método ou função declarado como function &name() não pode ser interceptado. Call contexts (contextos de chamada) e behaviors (comportamentos) retornam valores, então quem chama receberia uma cópia em vez da referência. Compilar um deles falha com uma WeavingException.
Exclua esses métodos de uma matching rule (regra de correspondência) abrangente com !matchReturningByReference():
#[Around('execution(public App\Service\*->*(*)) && !matchReturningByReference()')]Na 3.x, o call context retornava uma cópia com um notice. Na 4.0 é um erro, então você encontra esses métodos em tempo de compilação.
Métodos de trait com #[\Override]
Seção intitulada “Métodos de trait com #[\Override]”Um método que uma classe importa de uma trait e que carrega #[\Override] não pode ser interceptado nessa classe. O PHP copia o atributo para o alias privado que o proxy chama, e esse alias não sobrescreve nada. Compilar um deles falha com uma WeavingException.
Você tem quatro opções:
- Excluir os métodos de trait da regra com
&& !matchInherited(). - Excluir só esse método, por exemplo
&& !execution(public Foo->hello(*)). - Remover
#[\Override]da trait. - Mirar a própria trait, por exemplo
execution(public HelloTrait->hello(*)). A trait é compilada, o que funciona com#[\Override], e o behavior vale em toda classe que usa a trait.
Métodos de trait que uma classe herda da sua classe pai não são afetados.
Generators
Seção intitulada “Generators”Em um método que contém yield, o behavior roda quando o método é chamado, e proceed() retorna o objeto Generator. O behavior não vê os valores produzidos pelo yield: eles são gerados depois, enquanto quem chamou itera.
Parâmetros variádicos por referência
Seção intitulada “Parâmetros variádicos por referência”getArguments() lista os argumentos por posição. Um parâmetro variádico por referência (&...$values) é passado ao método original por valor.
#[\SensitiveParameter] em stack traces
Seção intitulada “#[\SensitiveParameter] em stack traces”O proxy mantém o atributo. Os frames do framework que carregam os argumentos como array os escondem: o __invoke() do call context, o __initialization() gerado e o new reescrito.
Duas funções internas entre o call context e o método original não conseguem escondê-los:
ReflectionMethod::invokeArgs(), para métodos de instância e construtoresforward_static_call_array(), para métodos estáticos
Os frames delas em Throwable::getTrace() ainda guardam o array de argumentos, que a forma textual do trace imprime como Array. Error trackers que coletam os argumentos dos frames enxergam esse array. Com zend.exception_ignore_args=On, o padrão de produção, nenhum frame tem argumentos.
strict_types dos proxies de função
Seção intitulada “strict_types dos proxies de função”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 que faz a chamada, antes de entrar no proxy.
Interceptação de propriedades
Seção intitulada “Interceptação de propriedades”Regras access(...) interceptam leituras e escritas de propriedades de instância por meio de property hooks nativos do PHP 8.4 no proxy gerado: os hooks gerados encaminham as leituras e escritas por call contexts ClassFieldAccess. Veja interceptação de propriedades para saber o que isso oferece. As seguintes propriedades são puladas de propósito:
| Propriedade | Por quê |
|---|---|
Propriedades static |
O PHP não tem property hooks para propriedades estáticas. É uma restrição do engine. |
Propriedades readonly, incluindo public private(set) readonly |
O PHP não permite hooks em propriedades readonly. |
Propriedades que já têm hooks get ou set |
O framework não consegue compor os seus hooks com hooks definidos por você. |
Propriedades final herdadas de classes pai |
Não suportado. |
Propriedades private herdadas |
Não suportado. |
Os alvos suportados são as propriedades declaradas na própria classe compilada, incluindo as promovidas no construtor, e as propriedades public e protected herdadas de classes pai.
Uma propriedade pulada não gera erro. Se a sua regra corresponder a ela, a propriedade fica de fora da interceptação sem nenhum aviso: o AdviceMatcher pula propriedades estáticas, readonly e com hooks antes que qualquer código de proxy seja gerado. O gerador de propriedades também recusa uma propriedade assim com uma WeavingException, como rede de segurança.
A visibilidade assimétrica em propriedades que não são readonly é preservada. public protected(set) string $name mantém seus modificadores na classe proxy.
Notas sobre o PHP 8.4
Seção intitulada “Notas sobre o PHP 8.4”O framework constrói a interceptação de propriedades sobre os property hooks do PHP 8.4, e o seu container usa lazy objects do PHP 8.4 para serviços adiados. Duas partes disso têm limites.
A inicialização de lazy objects não pode ser interceptada
Seção intitulada “A inicialização de lazy objects não pode ser interceptada”O PHP 8.4 introduziu ReflectionClass::newLazyProxy() e ReflectionClass::newLazyGhost() para a inicialização lazy de objetos. O Container do framework usa lazy proxies nativos para os seus próprios serviços adiados e para as behavior classes (classes de comportamento) registradas pelo nome da classe. Obter um desses serviços entrega uma instância newLazyProxy() tipada e correta para instanceof. A factory registrada só roda na primeira interação real com esse objeto.
Classes que o PHP não consegue tornar lazy recorrem à construção imediata: classes internas e suas subclasses que não derivam de stdClass, classes abstratas e enums.
Não existe call context para o momento em que um lazy proxy materializa a sua instância real, então a própria inicialização de lazy objects não pode ser interceptada.
Resumo do PHP 8.4
Seção intitulada “Resumo do PHP 8.4”| Recurso do PHP 8.4 | Suporte | Observações |
|---|---|---|
| Property hooks em propriedades novas | Gerados pelo framework | Usados para a interceptação com access(...) |
| Propriedades com hooks existentes | Puladas | O framework não consegue compor com hooks definidos pelo usuário |
| Propriedades readonly | Puladas | Hooks não são permitidos em propriedades readonly |
| Visibilidade assimétrica (não readonly) | Preservada | Os modificadores de visibilidade são copiados para o proxy |
Atributo #[\Deprecated] |
Propagado | Copiado para os métodos e as classes do proxy |
Lazy objects (newLazyProxy) |
Não interceptáveis | Sem call context para a inicialização lazy |
Notas sobre o PHP 8.5
Seção intitulada “Notas sobre o PHP 8.5”As notas sobre o PHP 8.5 se baseiam em uma auditoria do framework no PHP 8.5.10 e no PHP 8.6.0beta2.
O que funciona no PHP 8.5
Seção intitulada “O que funciona no PHP 8.5”- Operador pipe
|>. Funciona dentro dos corpos de métodos compilados. Os corpos de métodos são movidos literalmente para a body trait<Class>OriginalTrait, então qualquer sintaxe de expressão do PHP 8.5 dentro deles é preservada. clone with. Expressões em código compilado funcionam como esperado.#[\NoDiscard]. O atributo é copiado para o método de proxy gerado, e o call context retorna o valor do método interceptado. O aviso “return value not used” do engine continua disparando para métodos compilados.- Atributos em constantes de classe, incluindo
#[\Deprecated]. As constantes de classe permanecem na trait gerada junto com os seus atributos. - Closures e first-class callables como valores padrão de parâmetros. Eles sobrevivem à compilação nas assinaturas dos métodos de proxy.
- Visibilidade assimétrica estática. Propriedades
staticcom visibilidade assimétrica (public static private(set)) funcionam em classes compiladas. Elas nunca são alvo de regrasaccess(...). - Resolução de
selfeparentna reflection. No PHP 8.5,ReflectionNamedType::getName()resolve os tipos de retornoselfeparentpara nomes de classe concretos. Os geradores de proxy leem o nó de tipo bruto da AST quando ele está disponível, então as palavras-chaveselfeparentsão preservadas nos proxies gerados.
new em inicializadores não é interceptado
Seção intitulada “new em inicializadores não é interceptado”Uma expressão new dentro de uma expressão constante é avaliada pelo engine. Isso abrange o valor padrão de um parâmetro ou de um parâmetro promovido do construtor, o inicializador de uma variável estática e o argumento de um atributo. O compilador deixa essas expressões como estão, então o código funciona, mas um behavior initialization(...) não roda para os objetos que elas criam. Só as expressões new em código executável são interceptadas.
Propriedades estáticas nunca são interceptáveis
Seção intitulada “Propriedades estáticas nunca são interceptáveis”Propriedades estáticas, incluindo as propriedades static do PHP 8.5 com visibilidade assimétrica, não podem ser interceptadas com regras access(...). Property hooks não existem para propriedades estáticas, então o framework não tem mecanismo de interceptação para elas, e o AdviceMatcher as exclui da interceptação de propriedades. É uma restrição do engine do PHP, não um bug.
Resumo do PHP 8.5
Seção intitulada “Resumo do PHP 8.5”| Recurso do PHP 8.5 | Suporte | Observações |
|---|---|---|
Operador pipe |> em corpos de métodos |
Funciona | Os corpos são movidos literalmente para a trait gerada |
clone with |
Funciona | |
#[\NoDiscard] |
Propagado | Copiado para o proxy; o call context retorna o valor |
Atributos em constantes de classe (incluindo #[\Deprecated]) |
Preservados | As constantes permanecem na trait gerada |
| Closures e first-class callables como valores padrão de parâmetros | Funciona | |
| Visibilidade assimétrica estática (não interceptada) | Preservada | Propriedades estáticas nunca são interceptáveis com access() |
Resolução de self/parent na reflection |
Tratada | Nós de tipo brutos da AST são usados na geração de proxies |
new em inicializadores |
Não interceptado | Avaliado pelo engine; behaviors initialization(...) não rodam para ele |
Interceptação de propriedades estáticas com access() |
Nunca | Sem property hooks para propriedades estáticas (restrição do engine do PHP) |
Escopo de compilação e limites das matching rules
Seção intitulada “Escopo de compilação e limites das matching rules”Classes carregadas antes do boot do kernel
Seção intitulada “Classes carregadas antes do boot do kernel”Só são compiladas as classes carregadas depois que o kernel é inicializado. Uma classe carregada antes desse ponto roda sem os seus behaviors. Inicialize o kernel o mais cedo possível no seu front controller (controlador frontal). As bridges de frameworks precisam fazer o boot primeiro; veja em Integrações como cada bridge lida com isso.
Argumentos não podem ser selecionados
Seção intitulada “Argumentos não podem ser selecionados”A lista de argumentos em uma matching rule é sempre (*). Uma regra seleciona métodos por classe, nome, modificadores, tipo de retorno e atributos, nunca por valores de argumentos ou tipos de parâmetros. Para agir sobre argumentos específicos, case o método e inspecione $invocation->getArguments() dentro do behavior. A sintaxe completa está em Behaviors e matching rules.
Custos de runtime que vale conhecer
Seção intitulada “Custos de runtime que vale conhecer”Estes números vêm do benchmark do próprio framework em docs/performance.md: uma pequena aplicação de loja com cerca de 250 arquivos, 94 classes compiladas e 6 behavior classes, no PHP 8.5.12 com o JIT desativado. O arquivo explica como eles foram medidos e como reproduzi-los.
Regras initialization() afetam todo new
Seção intitulada “Regras initialization() afetam todo new”Enquanto houver uma regra initialization registrada, cada new nos arquivos gerados passa pelo transformer. Uma classe sem behaviors de inicialização (e com construtor público) ainda é criada por um new nativo, que custa cerca de 130 ns a mais que um new simples. Uma classe com behaviors de inicialização passa pelo call context completo. Prefira regras de método sempre que elas resolverem o problema.
O modo debug é para desenvolvimento
Seção intitulada “O modo debug é para desenvolvimento”Com 'debug' => true, as classes geradas são servidas pelo stream filter, para que os breakpoints do Xdebug e as constantes mágicas apontem para os seus arquivos originais, e os arquivos alterados são recompilados automaticamente. No benchmark, as requisições quentes em modo debug levam mais que o dobro do tempo do modo de produção. Use 'debug' => false em produção; veja Produção e desempenho.
Atualizando da 3.x para a 4.0
Seção intitulada “Atualizando da 3.x para a 4.0”A versão 4.0 substitui o compilador baseado em herança por um baseado em traits, gera os behaviors como first-class callables e reconstrói os caches para o PHP 8.4. A maioria das aplicações só precisa do checklist abaixo. As seções seguintes descrevem cada mudança incompatível. Os nomes de API nelas mantêm os termos clássicos; a tabela de termos os relaciona às palavras usadas aqui. A lista completa de mudanças está no CHANGELOG.
Checklist rápido
Seção intitulada “Checklist rápido”-
Rode no PHP 8.4 ou mais novo e atualize as dependências (veja Requisitos e dependências, abaixo).
-
Torne
publictodos os métodos de behavior das suas behavior classes (veja Behavior classes, abaixo). -
Registre as behavior classes com
add()ouaddLazyService()em vez deregisterAspect(). -
Substitua os curingas
?nas matching rules por*e reescreva as regrasdynamic(...). -
Apague o diretório de cache e depois aqueça-o de novo. O argumento é o arquivo que inicializa o seu kernel:
Janela do terminal vendor/bin/aspect cache:warmup:aop public/index.php -
Se você usa a bridge do Doctrine, troque a descoberta de entidades para
WovenEntityClassLocator.
Requisitos e dependências
Seção intitulada “Requisitos e dependências”- PHP 8.4+ com
ext-tokenizer. - Atualize as dependências com o Composer. As versões exigidas estão em
composer.json. psr/containeré uma dependência nova, enikic/php-parseré instalado viagoaop/parser-reflection.laminas/laminas-codenão é mais usado. Os proxies são gerados pelo pacote internoGo\Proxy\Generator. Código que estendia os geradores do framework, ou que dependia das classes geradoras do laminas que vinham junto com o framework, precisa ser atualizado.bin/aspectprecisa desymfony/console.
Todos os formatos de cache mudaram, e nenhum arquivo de cache da 3.x é reaproveitado.
- Layout dos proxies. O subdiretório
_proxiesdeixou de existir. Um proxy é armazenado no caminho relativo do seu arquivo-fonte abaixo do diretório de cache, e o fonte gerado (o corpo original da classe como uma trait<Class>OriginalTrait) fica ao lado dele. - Class map.
_include.cachemapeia cada classe compilada para o seu arquivo em cache e é entregue ao Composer no boot. Ele também mapeia cada arquivo-fonte conhecido para o seu arquivo em cache (ounull, quando não transformado) para os includes interceptados porINTERCEPT_INCLUDES. Um diretório de cache sem ele é tratado como desatualizado. - Cache das behavior classes. Os blobs serializados
{cacheDir}/_aspect/sha1(FQCN)foram substituídos por arquivos PHP simples ao lado dos fontes gerados:{appDir}/src/Aspect/LoggingAspect.phpfica em cache como{cacheDir}/src/Aspect/LoggingAspect.cache.php. Os interceptores deixaram de ser serializáveis:AbstractInterceptor::__serialize(),__unserialize(),serializeAdvice()eunserializeAdvice()foram removidos.
Os arquivos de metadados trazem uma versão de formato. Com Features::PREBUILT_CACHE, um cache gerado por outra versão do framework é rejeitado com uma exceção, em vez de ser reconstruído em tempo de execução.
Features::PREBUILT_CACHE agora confia totalmente no cache. As sondagens de diretório e de permissão de escrita, as comparações de filemtime, as verificações de recursos acompanhados e as verificações de atualização dos caches das behavior classes são todas puladas. Gerar o cache de novo no deploy é responsabilidade de quem faz o deploy.
A opção cacheFileMode é validada. Ela precisa ser um inteiro entre 0600 e 0777 que dê ao dono permissão de leitura e escrita. Os diretórios recebem permissões de busca correspondentes aos bits de leitura do modo.
Behavior classes
Seção intitulada “Behavior classes”Os métodos de behavior precisam ser públicos
Seção intitulada “Os métodos de behavior precisam ser públicos”Os proxies gerados chamam os behaviors como first-class callables na instância da behavior class. Por isso, um método com #[Before], #[After], #[Around] ou #[AfterThrowing] precisa ser public. O loader lança uma AspectException para métodos de behavior protected ou private. Métodos que só carregam #[Pointcut] podem ter qualquer visibilidade.
#[Before('execution(public Example->*(*))')]protected function beforeMethod(MethodInvocation $invocation): void {}
// 4.0#[Before('execution(public Example->*(*))')]public function beforeMethod(MethodInvocation $invocation): void {}Um atributo de behavior por método
Seção intitulada “Um atributo de behavior por método”Um método de uma behavior class carrega no máximo um entre #[Before], #[After], #[Around] e #[AfterThrowing]. Um segundo lança uma AspectException. Divida um método assim em um método por behavior. #[Pointcut] ainda pode ser combinado com um atributo de behavior no mesmo método, e atributos que não pertencem ao framework são ignorados.
Registrando behavior classes
Seção intitulada “Registrando behavior classes”AspectContainer::registerAspect() foi removido. As behavior classes são serviços comuns do container.
Antes, na 3.x:
// 3.xprotected function configureAop(AspectContainer $container){ $container->registerAspect(new MonitorAspect());}Depois, na 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 uma factory e constrói o serviço na primeira vez que ele é obtido. Código que esperava que uma instância lazy proxy existisse no boot precisa chamar getService(). Uma factory que retorna um objeto do tipo errado agora falha no primeiro uso, não no registro.
AspectContainer::addResource() faz parte da interface. onRegistration() permite reagir a registros adiados de serviços que implementam uma interface.
Container PSR-11
Seção intitulada “Container PSR-11”AspectContainer estende Psr\Container\ContainerInterface, então você pode passar o container para qualquer código que espere um container PSR-11.
AspectContainer::getValue()foi renomeado paraget().has()vem da interface PSR, com a mesma assinatura.- Um
containerClasspersonalizado implementaget()em vez degetValue(), além desetDelegate(), que acopla o container da sua aplicação. Veja Configuração e CLI.
// before$pointcut = $container->getValue('my.pointcut');
$pointcut = $container->get('my.pointcut');Um id desconhecido lança ServiceNotFoundException, que implementa Psr\Container\NotFoundExceptionInterface. getService() lança Go\Aop\Exception\ContainerException quando a entrada não é uma instância da classe pedida. Essa exceção é uma InvalidConfigurationException que implementa Psr\Container\ContainerExceptionInterface.
A renomeação vale só para o container. FieldAccess::getValue() nos call contexts de propriedade não mudou.
API de Advice e de interceptores
Seção intitulada “API de Advice e de interceptores”- As marker interfaces
AdviceBefore,AdviceAftereAdviceAroundforam removidas.AdviceexigegetType(): AdviceTypeEnum, com os casesBefore,After,AfterThrowing,AroundeIntroduction. - Os construtores de invocation (
DynamicTraitAliasMethodInvocation,StaticTraitAliasMethodInvocation,ReflectionFunctionInvocation) exigem umClosure $closureToCallnão anulável. DeclareErrorfoi removido: o atributo,DeclareErrorInterceptorePointcutBuilder::declareError(). Em vez disso, emita warnings ou lance exceções a partir de um behavior#[Before]ou#[Around].
Matching rules
Seção intitulada “Matching rules”Métodos que retornam por referência são rejeitados
Seção intitulada “Métodos que retornam por referência são rejeitados”Compilar um método ou função declarado como function &name() falha com uma WeavingException, porque o call context retornaria uma cópia em vez da referência. A 3.x retornava uma cópia com um notice. Acrescente && !matchReturningByReference() às regras que selecionam esses métodos.
O curinga ? foi removido
Seção intitulada “O curinga ? foi removido”? em padrões de nome e de tipo deixou de ser um curinga de um único caractere, porque colidia com os tipos anuláveis. Em padrões de tipo de retorno, um ? no início marca o tipo como anulável: ?Foo equivale a Foo|null. Substitua os curingas ? por *.
dynamic(...) foi removido
Seção intitulada “dynamic(...) foi removido”A regra dynamic(...) foi removida, junto com MagicMethodDynamicPointcut, DynamicInvocationMatcherInterceptor, Pointcut::KIND_DYNAMIC e os parâmetros $instanceOrScope e $arguments de Pointcut::matches(). Intercepte o próprio método mágico e leia o nome invocado a partir dos argumentos.
Antes, na 3.x:
#[Around('dynamic(public Foo->save*(*))')]Depois, na 4.0:
#[Around('execution(public Foo->__call(*))')]public function aroundMagicCall(MethodInvocation $invocation): mixed{ [$methodName, $arguments] = $invocation->getArguments(); // ... return $invocation->proceed();}Matching rules que mudaram
Seção intitulada “Matching rules que mudaram”- Precedência de modificadores. Modificadores separados por espaço precisam estar todos presentes, e
|tem precedência maior.final public|protectedsignifica final E (public OU protected). Na 3.x, isso também casava com todo método public que não fosse final. Foo+incluiFoo. Agora corresponde também à própria classe ou interfaceFooe às classes que usam a traitFoo. Acrescente&& !within(Foo)para excluir o próprio tipo.- Regras de atributo correspondem a subclasses.
@execution(Attr)e as demais regras de atributo também correspondem a atributos que estendemAttr. *também corresponde a nada. Em padrões de nome e de tipo de retorno,*representa quaisquer caracteres de uma parte do nome, inclusive nenhum. Na 3.x, exigia pelo menos um caractere:Sensor*pulava a própria classeSensor, eset*pulava um método chamadoset(). Agora essas regras correspondem a eles também. Exclua-os com&& !execution(public Foo->set(*))ou&& !within(Foo), se necessário.- Alternativas com
|ficam dentro da sua parte do nome.Ns\A|BselecionaNs\AeNs\B. Na 3.x, significavaNs\Aou a classe globalB. Um padrão que listava classes de namespaces diferentes (Foo\A|Bar\B) precisa ser escrito como duas regras:execution(public Foo\A->*(*)) || execution(public Bar\B->*(*)). ModifierPointcuté final e imutável. As máscaras são argumentos do construtor, eandMatch(),orMatch()enotMatch()retornam uma nova instância.
Compilador e código gerado
Seção intitulada “Compilador e código gerado”O corpo original da classe é convertido em uma trait, <Class>OriginalTrait. A classe proxy mantém o nome, a classe pai e as interfaces originais, e usa essa trait com aliases privados <method>OriginalAlias. Na 3.x, o proxy estendia uma classe pai renomeada, <Class>__AopProxied. Isso afeta o código que dependia dessa camada de herança:
- O proxy não tem mais uma classe pai renomeada.
get_parent_class(),parent::dentro da classe e as verificaçõesinstanceofveem a classe pai original. AspectContainer::AOP_PROXIED_SUFFIXfoi removido. UseORIGINAL_TRAIT_SUFFIX('OriginalTrait') ouORIGINAL_TRAIT_FILE_SUFFIX('OriginalTrait.php').AbstractMethodInvocation::TRAIT_ALIAS_PREFIXfoi substituído porTRAIT_ALIAS_SUFFIX('OriginalAlias').- Os hooks de
InitializationAwareeStaticInitializationAwarese chamam__initialization()e__staticInitialization(). self::no código gerado resolve para a classe proxy, por issoSelfValueTransformereSelfValueVisitorforam removidos.Go\Aop\Featuresé uma classe final em vez de uma interface. As constantes não mudaram, mas ela não pode mais ser implementada.Features::ALLcombina todas as flags, eAspectKernel::hasFeature()lança uma exceção para uma flag desconhecida.Features::PARAMETER_WIDENINGfoi removido. Apague a flag das opções do seu kernel, se você a passava.
API sem uso removida
Seção intitulada “API sem uso removida”Estas classes, métodos e constantes públicos não tinham uso dentro do framework e foram removidos:
- O atributo
#[Aspect](Go\Lang\Attribute\Aspect). O framework nunca o lia: as behavior classes são identificadas por implementaremGo\Aop\Aspect. Remova o atributo das suas behavior classes. Pointcut::KIND_TRAIT.Pointcut::KIND_ALLpassa a ser119em vez de127.Go\Proxy\Part\InterceptedConstructorGeneratoreGo\Proxy\Part\FunctionParameterList.InterceptedMethodGenerator::getBody()esetBody(),CachePathManager::setCacheDir()eAopComposerLoader::wasInitialized().AopComposerLoader::init()retorna a mesma flag.- A entrada de container
'kernel.options'. UseAspectKernel::getOptions().
Enums e constantes renomeados
Seção intitulada “Enums e constantes renomeados”| 3.x / desenvolvimento inicial da 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) |
Os enums de Go\Proxy\Generator (Visibility, PropertyModifier, ClassModifier) também usam cases em PascalCase. Source transformers personalizados retornam cases de TransformerResult, e behaviors que comparam getAccessType() usam os novos nomes de case:
if ($access->getAccessType() === FieldAccessType::WRITE) {if ($access->getAccessType() === FieldAccessType::Write) {Kernel e transformers
Seção intitulada “Kernel e transformers”AspectKernel::registerTransformers(), que retornava instâncias de transformers, foi substituído porregisterTransformerServices(AspectContainer $container), que registra serviços adiados no container. Sobrescreva-o para substituir, omitir, reordenar ou estender os transformers embutidos. Para acrescentar um, chame$container->addLazyService(MyTransformer::class, ...)a partir deconfigureAop().CachingTransformerfoi removido: a decisão sobre o cache fica emSourceTransformingLoader.SourceTransformingLoader::addTransformer()foi removido, etransformCode()retorna oTransformerResultgeral.StreamMetaData::$sourceé somente leitura: ele é reconstruído a partir de$tokenStreama cada leitura. Transformers personalizados editam os tokens em$tokenStreamou os substituem comsetTokenStreamFromRawTokens().ConstructorExecutionTransformer,FilterInjectorTransformereMagicConstantTransformerdeixaram de serSourceTransformers. Eles são regrasNodeRewriter, aplicadas por uma única travessiaSyntaxTreeRewriterda árvore sintática. Essa travessia é um serviço do framework: ela abre a cadeia antes doWeavingTransformer, mesmo quandoregisterTransformerServices()é sobrescrito.SourceTransformers personalizados são registrados como antes. Para reescrever nós individuais, registre um serviçoNodeRewriterem vez de um transformer que percorre a árvore por conta própria. Veja em Configuração e CLI como estender o pipeline de transformação.
Classes final e internas
Seção intitulada “Classes final e internas”Classes que nunca foram feitas para serem estendidas agora são final:
Go\Core\Container,Go\Core\AttributeAspectLoaderExtensionGo\Aop\Framework\StaticInitializationJoinpointGo\Instrument\ClassLoading\AopComposerLoader,SourceTransformingLoader,Go\Instrument\PathResolver- os transformers
WeavingTransformer,FilterInjectorTransformer,MagicConstantTransformereStreamMetaData - os geradores de proxy
EnumProxyGenerator,TraitProxyGeneratoreFunctionProxyGenerator - os atributos
#[Before],#[After],#[Around],#[AfterThrowing],#[Pointcut]e#[DeclareParents]
Go\Lang\Attribute\AbstractInterceptor é abstract. As classes que fazem parte apenas da maquinaria do framework estão marcadas como @internal e não são cobertas pelas promessas de BC (compatibilidade retroativa): AdviceMatcher, AspectLoader, CachedAspectLoader, CachePathManager, CacheWarmer, Enumerator, InterceptorInjector, The e NativeLazyProxy.
Substitua as subclasses dessas classes por composição, ou pelo seu próprio container ou transformer registrado em configureAop() ou registerTransformerServices().
Exceções
Seção intitulada “Exceções”Toda exceção lançada pelo framework implementa Go\Aop\Exception\ExceptionInterface, então um único catch trata qualquer uma das suas falhas. Vários pontos de lançamento mudaram de tipo:
| Situação | 3.x | 4.0 |
|---|---|---|
| Opções de kernel inválidas, registros no container, entrada do console | RuntimeException, InvalidArgumentException, UnexpectedValueException |
InvalidConfigurationException (uma InvalidArgumentException) |
| Matching rule inválida | UnexpectedValueException, InvalidArgumentException |
PointcutSyntaxException (uma AspectException) |
| Id de container desconhecido | OutOfBoundsException |
ServiceNotFoundException (uma OutOfBoundsException e uma NotFoundExceptionInterface do PSR-11) |
Entrada de container do tipo errado em getService() |
InvalidArgumentException |
ContainerException (uma InvalidConfigurationException e uma ContainerExceptionInterface do PSR-11) |
| Compilação, geração de proxies, gravações de cache | RuntimeException, LogicException, InvalidArgumentException |
WeavingException (uma RuntimeException) |
| Behavior que não pode ser colocado em cache | Go\Core\Cache\NotCompilableException |
Go\Aop\Exception\NotCompilableException |
| Behavior class inválida, erros de runtime do call context | Go\Aop\AspectException |
Go\Aop\Exception\AspectException, Go\Aop\Exception\InvocationException |
Onde você capturava os tipos SPL listados acima, capture ExceptionInterface ou os novos tipos.
Bridge do Doctrine
Seção intitulada “Bridge do Doctrine”A bridge não reescreve mais os metadados das entidades. O contorno de mapped superclass da 3.x só se aplicava ao engine baseado em herança (extends), e o Doctrine mapeia uma entidade compilada corretamente como ela está. Em vez disso, configure duas coisas (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());Console
Seção intitulada “Console”Os comandos declaram seus nomes com #[AsCommand] e são carregados de forma lazy pelo bin/aspect. Todo comando retorna Command::SUCCESS ou Command::FAILURE.
- Na 3.x,
debug:weavingretornava a contagem bruta de erros. Se um script dependia desse número, verifique o código de saída. cache:warmup:aopfalha quando um arquivo não pode ser compilado, então um script de deploy que ignorava os erros do aquecimento agora para ali. Acrescente--fail-fastpara parar no primeiro erro:
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast© 2026 Alexander Lisachenko
