Pular para o conteúdo
Documentação · Integrações

Symfony

Integração com o Symfony via goaop/goaop-symfony-bundle 4.0: behavior classes com autoconfiguração, um painel no web profiler e aquecimento do cache.

Traduzido do inglês. A página em inglês é a referência. Ler o original

O bundle goaop/goaop-symfony-bundle 4.0 acopla behaviors (comportamentos) aos seus serviços à medida que eles são carregados. Você não precisa de classes base nem de decorators.

namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect
{
public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('{method} took {ms} ms', [
'method' => (string) $invocation,
'ms' => (hrtime(true) - $start) / 1e6,
]);
}
}
}

Essa é a integração inteira. A classe implementa Go\Aop\Aspect, então a autoconfiguração a registra como uma behavior class (classe de comportamento), e o autowiring lhe entrega o logger. A partir da próxima requisição, todo método público de toda classe abaixo de App\Service é cronometrado.

  • PHP 8.4 ou mais novo
  • Symfony 7.4 ou 8.x
  • goaop/framework ^4.0 (behaviors declarados com atributos)
Janela do terminal
composer require goaop/goaop-symfony-bundle

Registre o bundle como a primeira entrada de config/bundles.php:

config/bundles.php
return [
Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true],
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
// ...
];

A compile step (etapa de compilação) só se aplica às classes carregadas depois que o kernel é inicializado, e os bundles fazem o boot na ordem em que foram registrados. O bundle garante isso: se ele não for o primeiro, o build do container falha com uma mensagem clara.

O arquivo de configuração é opcional. Com os padrões abaixo, o bundle compila o diretório src/ no modo do kernel e ativa o cache pré-gerado em produção:

config/packages/go_aop.yaml
go_aop:
include_paths: ['%kernel.project_dir%/src']
when@prod:
go_aop:
features: [PREBUILT_CACHE]

bin/console config:dump-reference go_aop imprime a referência completa. Todas as opções, com seus padrões:

config/packages/go_aop.yaml
go_aop:
# Development mode: changed sources and behavior classes are compiled again on the next request,
# breakpoints work in the original files. Keep it off in production.
debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it.
app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir%
# or %kernel.build_dir% so that cache:clear and cache:warmup manage it.
cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer.
# Defaults to 0770 minus the umask.
cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed.
include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the
# framework itself are always excluded).
exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each).
parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant:
# PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime
# INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code)
# PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not
# locate, with their own members
features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize
# the transformation pipeline.
kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear.
cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered.
doctrine: ~

Variáveis de ambiente funcionam como em qualquer lugar do Symfony, por exemplo debug: '%env(bool:GOAOP_DEBUG)%'. Matching rules (regras de correspondência) de função e de initialization() não precisam de feature flag: elas mesmas ligam a sua maquinaria.

Uma behavior class é um serviço comum com autowiring. A autoconfiguração registra todo serviço que implementa Go\Aop\Aspect. Sem autoconfiguração, marque o serviço com a tag goaop.aspect:

services:
Acme\Audit\AuditAspect:
tags: [goaop.aspect]

Uma behavior class é um singleton: registrá-la como dois serviços é um erro de compilação do container.

O compilador só precisa das behavior classes. O container do Symfony cria uma behavior class quando um dos seus behaviors roda pela primeira vez, nunca durante a compile step ou o aquecimento do cache. O container do kernel (AspectContainer) também delega ao container do Symfony, então $aspectContainer->get(LoggerInterface::class) funciona. Go\Core\AspectKernel e Go\Core\AspectContainer são serviços disponíveis para autowiring, e goaop.aspect_kernel é público.

Confira o que uma behavior class seleciona antes de depender dela:

Janela do terminal
bin/console debug:aspect # behavior classes with their rules and behaviors
bin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matches

Em modo debug, as classes abaixo dos include paths são compiladas no primeiro carregamento e compiladas de novo quando o seu fonte ou uma behavior class muda.

Com o symfony/web-profiler-bundle instalado, a toolbar mostra o número de behavior classes. O painel Go! AOP lista:

  • as behavior classes com seus advisors, atributos de behavior e matching rules;
  • as classes compiladas carregadas durante a requisição, com seus arquivos de proxy;
  • as classes abaixo dos include paths que foram carregadas antes da inicialização do kernel (o painel fica amarelo);
  • a configuração efetiva do kernel.

A terceira lista é o diagnóstico para um bundle que faz o boot antes do GoAopBundle e para a única requisição que reconstruiu o container. Essa requisição precisa carregar as classes de serviço antes do boot do bundle, então as executa uma vez sem os seus behaviors. A requisição seguinte já roda totalmente compilada. Os deploys não são afetados, porque cache:clear e cache:warmup geram o container e o cache do framework juntos.

O bundle também desliga a opção .container.dumper.inline_class_loader do Symfony, a menos que a sua configuração a defina. Essa opção inclui os arquivos de serviço diretamente, o que contorna o class loader e, portanto, a compile step.

Janela do terminal
composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts
# or explicitly
bin/console cache:clear
bin/console cache:warmup

cache:clear e cache:warmup compilam a aplicação inteira por meio de um cache warmer. cache:clear gera o novo cache ao lado do que está em uso e depois o renomeia. O warmer gera o cache do framework nesse novo diretório, do zero, então os seus passos habituais de deploy não precisam mudar. O aquecimento falha quando um arquivo não pode ser compilado, então o deploy para em vez de publicar um cache incompleto. Rode cache:warmup:aop --fail-fast -vvv para ver o arquivo e o erro.

Os comandos do framework são registrados no console da sua aplicação. Eles trabalham sobre o kernel em execução, então você omite o argumento loader do vendor/bin/aspect.

Comando Finalidade
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] Compila para o cache todos os arquivos abaixo dos include paths. Falha quando um arquivo não pode ser compilado. --preload também grava o script opcache.preload do cache.
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] Pré-aquece o file cache do opcache (opcache.file_cache) com o cache do framework e a aplicação. Rode-o na imagem final.
debug:aspect [--aspect=FQCN] Lista as behavior classes com suas matching rules e advisors.
debug:advisor [--advisor=ID] Lista os advisors; com --advisor, aquilo que esse advisor seleciona.
debug:weaving [-v] Compila a aplicação duas vezes e reporta os proxies que diferem, o que aponta para uma behavior class não determinística.

Aqui, cache:warmup:aop --workers=N compila em um único processo: os seus processos worker fariam o boot do kernel com um arquivo loader, e o console da aplicação não tem nenhum.

config/packages/go_aop.yaml
when@prod:
go_aop:
features: [PREBUILT_CACHE]

Com PREBUILT_CACHE, o runtime pula todas as verificações de sistema de arquivos ligadas ao cache e nunca compila nem grava no diretório de cache. Uma classe abaixo dos include paths que o cache não conhece falha com uma WeavingException (“… is missing from the prebuilt AOP cache …”). Gere o cache de novo a cada deploy. Esta é a configuração de produção recomendada, e é ela que faz funcionar sistemas de arquivos somente leitura e imagens imutáveis.

Se o seu kernel.build_dir for diferente de kernel.cache_dir, ancore o cache do framework no diretório que você gera no deploy: cache_dir: '%kernel.build_dir%/aop'.

Para o preloading do opcache, faça require do script de preload do cache do framework antes do arquivo de preload do container:

config/preload.php
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) {
require $aop;
}
if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
require $container;
}

Em modo de produção, o cache warmer grava _preload.php no diretório de cache do framework. Ajuste esse caminho quando cache_dir não for %kernel.cache_dir%/aop. Não faça o boot do kernel em config/preload.php: isso falha com “Cannot redeclare class”. Mais sobre builds de produção: Produção e desempenho.

Quando o DoctrineBundle está registrado, ou quando você define doctrine: true, o bundle:

  • substitui a varredura de diretórios de todo driver de atributos do ORM por Go\Bridge\Doctrine\WovenEntityClassLocator, que carrega as entidades pelo class loader, para que elas mantenham os seus behaviors;
  • registra Go\Bridge\Doctrine\MetadataLoadInterceptor como listener de loadClassMetadata, que reporta, no carregamento dos metadados, uma propriedade de entidade interceptada quando os lazy objects nativos estão desligados.

As entidades precisam estar abaixo de um include path para serem compiladas. Os behaviors delas então se aplicam tanto quando o seu código as cria quanto quando o ORM as hidrata. A página Doctrine ORM explica as duas classes.

  • Um behavior não se aplica. Rode primeiro debug:advisor --advisor=...: ele lista o que uma matching rule seleciona. Depois verifique se a classe está abaixo de um include path e se ela não é carregada antes do boot do bundle (painel do profiler, classes loaded before weaving). Código de vendor só é compilado quando o seu diretório é um include path.

  • “Class … is missing from the prebuilt AOP cache”. O deploy publicou código para o qual o cache não foi gerado. Rode bin/console cache:clear (ou cache:warmup) depois que o código estiver no lugar.

  • “Circular reference detected for the aspect …”. Criar uma das dependências da behavior class executa um behavior dessa mesma classe. Injete a dependência de forma lazy ou restrinja a matching rule:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • “Class … was not found by locator”. Uma classe abaixo dos include paths estende código que o Composer não consegue localizar, como uma classe base gerada. Deixe o Composer localizá-la, ative PARTIAL_REFLECTION ou exclua as classes dependentes com exclude_paths.

  • Handlers de exceção. Exclua com exclude_paths as classes que precisam carregar quando todo o resto já falhou (handlers de erro, o kernel).

© 2026 Alexander Lisachenko