Pular para o conteúdo
Documentação

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”

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.

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.

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.

getArguments() lista os argumentos por posição. Um parâmetro variádico por referência (&...$values) é passado ao método original por valor.

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 construtores
  • forward_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.

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.

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.

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.

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

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.

  • 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 static com visibilidade assimétrica (public static private(set)) funcionam em classes compiladas. Elas nunca são alvo de regras access(...).
  • Resolução de self e parent na reflection. No PHP 8.5, ReflectionNamedType::getName() resolve os tipos de retorno self e parent para 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-chave self e parent são preservadas nos proxies gerados.

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.

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”

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.

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.

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.

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.

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.

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.

  1. Rode no PHP 8.4 ou mais novo e atualize as dependências (veja Requisitos e dependências, abaixo).

  2. Torne public todos os métodos de behavior das suas behavior classes (veja Behavior classes, abaixo).

  3. Registre as behavior classes com add() ou addLazyService() em vez de registerAspect().

  4. Substitua os curingas ? nas matching rules por * e reescreva as regras dynamic(...).

  5. 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
  6. Se você usa a bridge do Doctrine, troque a descoberta de entidades para WovenEntityClassLocator.

  • 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, e nikic/php-parser é instalado via goaop/parser-reflection.
  • laminas/laminas-code não é mais usado. Os proxies são gerados pelo pacote interno Go\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/aspect precisa de symfony/console.

Todos os formatos de cache mudaram, e nenhum arquivo de cache da 3.x é reaproveitado.

  • Layout dos proxies. O subdiretório _proxies deixou 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.cache mapeia 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 (ou null, quando não transformado) para os includes interceptados por INTERCEPT_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.php fica em cache como {cacheDir}/src/Aspect/LoggingAspect.cache.php. Os interceptores deixaram de ser serializáveis: AbstractInterceptor::__serialize(), __unserialize(), serializeAdvice() e unserializeAdvice() 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.

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.

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

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.

AspectContainer::registerAspect() foi removido. As behavior classes são serviços comuns do container.

Antes, na 3.x:

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

Depois, na 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 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.

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 para get().
  • has() vem da interface PSR, com a mesma assinatura.
  • Um containerClass personalizado implementa get() em vez de getValue(), além de setDelegate(), que acopla o container da sua aplicação. Veja Configuração e CLI.
4.0
// 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.

  • As marker interfaces AdviceBefore, AdviceAfter e AdviceAround foram removidas. Advice exige getType(): AdviceTypeEnum, com os cases Before, After, AfterThrowing, Around e Introduction.
  • Os construtores de invocation (DynamicTraitAliasMethodInvocation, StaticTraitAliasMethodInvocation, ReflectionFunctionInvocation) exigem um Closure $closureToCall não anulável.
  • DeclareError foi removido: o atributo, DeclareErrorInterceptor e PointcutBuilder::declareError(). Em vez disso, emita warnings ou lance exceções a partir de um behavior #[Before] ou #[Around].

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.

? 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 *.

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:

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

Depois, na 4.0:

4.0
#[Around('execution(public Foo->__call(*))')]
public function aroundMagicCall(MethodInvocation $invocation): mixed
{
[$methodName, $arguments] = $invocation->getArguments();
// ...
return $invocation->proceed();
}
  • Precedência de modificadores. Modificadores separados por espaço precisam estar todos presentes, e | tem precedência maior. final public|protected significa final E (public OU protected). Na 3.x, isso também casava com todo método public que não fosse final.
  • Foo+ inclui Foo. Agora corresponde também à própria classe ou interface Foo e às classes que usam a trait Foo. 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 estendem Attr.
  • * 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 classe Sensor, e set* pulava um método chamado set(). 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|B seleciona Ns\A e Ns\B. Na 3.x, significava Ns\A ou a classe global B. 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, e andMatch(), orMatch() e notMatch() retornam uma nova instância.

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ções instanceof veem a classe pai original.
  • AspectContainer::AOP_PROXIED_SUFFIX foi removido. Use ORIGINAL_TRAIT_SUFFIX ('OriginalTrait') ou ORIGINAL_TRAIT_FILE_SUFFIX ('OriginalTrait.php').
  • AbstractMethodInvocation::TRAIT_ALIAS_PREFIX foi substituído por TRAIT_ALIAS_SUFFIX ('OriginalAlias').
  • Os hooks de InitializationAware e StaticInitializationAware se chamam __initialization() e __staticInitialization().
  • self:: no código gerado resolve para a classe proxy, por isso SelfValueTransformer e SelfValueVisitor foram 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::ALL combina todas as flags, e AspectKernel::hasFeature() lança uma exceção para uma flag desconhecida.
  • Features::PARAMETER_WIDENING foi removido. Apague a flag das opções do seu kernel, se você a passava.

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 implementarem Go\Aop\Aspect. Remova o atributo das suas behavior classes.
  • Pointcut::KIND_TRAIT. Pointcut::KIND_ALL passa a ser 119 em vez de 127.
  • Go\Proxy\Part\InterceptedConstructorGenerator e Go\Proxy\Part\FunctionParameterList.
  • InterceptedMethodGenerator::getBody() e setBody(), CachePathManager::setCacheDir() e AopComposerLoader::wasInitialized(). AopComposerLoader::init() retorna a mesma flag.
  • A entrada de container 'kernel.options'. Use AspectKernel::getOptions().
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) {
  • AspectKernel::registerTransformers(), que retornava instâncias de transformers, foi substituído por registerTransformerServices(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 de configureAop().
  • CachingTransformer foi removido: a decisão sobre o cache fica em SourceTransformingLoader. SourceTransformingLoader::addTransformer() foi removido, e transformCode() retorna o TransformerResult geral.
  • StreamMetaData::$source é somente leitura: ele é reconstruído a partir de $tokenStream a cada leitura. Transformers personalizados editam os tokens em $tokenStream ou os substituem com setTokenStreamFromRawTokens().
  • ConstructorExecutionTransformer, FilterInjectorTransformer e MagicConstantTransformer deixaram de ser SourceTransformers. Eles são regras NodeRewriter, aplicadas por uma única travessia SyntaxTreeRewriter da árvore sintática. Essa travessia é um serviço do framework: ela abre a cadeia antes do WeavingTransformer, mesmo quando registerTransformerServices() é sobrescrito.
  • SourceTransformers personalizados são registrados como antes. Para reescrever nós individuais, registre um serviço NodeRewriter em 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 que nunca foram feitas para serem estendidas agora são final:

  • Go\Core\Container, Go\Core\AttributeAspectLoaderExtension
  • Go\Aop\Framework\StaticInitializationJoinpoint
  • Go\Instrument\ClassLoading\AopComposerLoader, SourceTransformingLoader, Go\Instrument\PathResolver
  • os transformers WeavingTransformer, FilterInjectorTransformer, MagicConstantTransformer e StreamMetaData
  • os geradores de proxy EnumProxyGenerator, TraitProxyGenerator e FunctionProxyGenerator
  • 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().

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.

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());

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:weaving retornava a contagem bruta de erros. Se um script dependia desse número, verifique o código de saída.
  • cache:warmup:aop falha 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-fast para parar no primeiro erro:
Janela do terminal
vendor/bin/aspect cache:warmup:aop public/index.php --fail-fast

© 2026 Alexander Lisachenko