Configuração e CLI
Configure o kernel, escolha as feature flags, forneça às behavior classes as dependências do container da sua aplicação e use o console.
Traduzido do inglês. A página em inglês é a referência. Ler o original
Tudo o que o framework precisa saber sobre a sua aplicação passa por uma única chamada: init() no seu kernel. Esta página lista todas as opções que o kernel aceita, as feature flags, como as behavior classes (classes de comportamento) recebem dependências do container da sua aplicação e o console vendor/bin/aspect, que você usa para gerar e inspecionar o cache.
O kernel
Seção intitulada “O kernel”Seu kernel estende Go\Core\AspectKernel e registra em configureAop() as behavior classes, que na API se chamam aspects (aspectos; veja a tabela de termos):
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect()); }}Você o inicializa uma vez, normalmente no front controller (controlador frontal), logo depois do autoloader do Composer:
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'],]);Opções do kernel
Seção intitulada “Opções do kernel”Só as opções abaixo são aceitas. Uma chave desconhecida, um containerClass desconhecido ou um bit de feature desconhecido lança Go\Aop\Exception\InvalidConfigurationException, então um erro de digitação falha na inicialização em vez de ser ignorado.
| Opção | Tipo | Padrão | Finalidade |
|---|---|---|---|
cacheDir |
string |
nenhum, obrigatória | Diretório dos fontes compilados, dos proxies, dos caches de advisors e do class map. |
appDir |
string |
o diretório que contém vendor/ |
Raiz da aplicação. Os caminhos no cache espelham os caminhos dos fontes relativos a ela, e só os arquivos abaixo dela são compilados. |
debug |
bool |
false |
Modo de desenvolvimento: mudanças no arquivo do kernel e nos arquivos de behavior classes invalidam o cache, e toda classe e todo include passam pelo stream filter de compilação do framework. Com false, as classes compiladas são carregadas do cache pelo class map do Composer. Use false em produção. |
includePaths |
string[] |
[] (tudo abaixo de appDir) |
Diretórios que são compilados. Mantenha a lista restrita: compilar código de vendor é lento e raramente necessário. |
excludePaths |
string[] |
[] |
Diretórios que nunca são compilados. O diretório de cache, o próprio framework e suas dependências de runtime (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) são sempre excluídos. |
features |
int |
0 |
Bitmask de flags de Go\Aop\Features; veja a próxima seção. |
cacheFileMode |
int |
0770 menos a umask |
Permissões dos arquivos de cache. Precisa estar entre 0600 e 0777 e dar ao dono acesso de leitura e escrita; os diretórios recebem os bits de busca correspondentes. |
containerClass |
class-string |
Go\Core\Container |
Implementação do container do kernel. Precisa implementar Go\Core\AspectContainer (um ContainerInterface PSR-11). |
parsedFilesLimit |
int |
100 |
Quantidade de arquivos-fonte parseados (árvores sintáticas, cerca de 0,2 MB cada) que o goaop/parser-reflection mantém em memória durante a compilação. Precisa ser um inteiro positivo: mais significa menos reparsing, menos significa menos memória. Substitui um limite definido com ReflectionEngine::setMaximumCachedFiles() antes de init() e é o padrão de cache:warmup:aop --cached-files. |
Feature flags
Seção intitulada “Feature flags”As feature flags são constantes da classe final Go\Aop\Features. Combine-as com |:
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,]);Features::ALL combina todas as flags. AspectKernel::hasFeature() diz se uma flag está ligada e lança exceção para uma flag desconhecida.
| Flag | Use quando |
|---|---|
INTERCEPT_INCLUDES |
Sua aplicação carrega código com include/require em vez do Composer. |
PREBUILT_CACHE |
Você gera o cache no deploy e quer que as requisições confiem totalmente nele. A configuração de produção. |
PARTIAL_REFLECTION |
Uma classe que você quer compilar estende ou implementa algo que o framework não consegue localizar. |
INTERCEPT_INCLUDES
Seção intitulada “INTERCEPT_INCLUDES”Passa include e require dos arquivos compilados pelo compilador. Use para código legado que não é carregado pelo Composer.
PREBUILT_CACHE
Seção intitulada “PREBUILT_CACHE”Confia totalmente no cache gerado no deploy. O kernel pula as sondagens do diretório de cache e de permissão de escrita, as comparações de filemtime dos fontes, as verificações de recursos monitorados e as verificações de atualidade dos caches de advisors. Uma requisição nunca compila e nunca grava no diretório de cache, então funciona em sistemas de arquivos somente leitura.
O outro lado: o cache precisa estar completo. Arquivos que o compilador nunca processa (fora dos include paths, excluídos, que não são .php, por exemplo um template incluído) são carregados como estão. Todo o resto abaixo dos include paths precisa ter um registro no cache.
O próprio cache:warmup:aop não confia no cache que gera. Rodado sobre um diretório existente, ele compila de novo todo arquivo cujo fonte mudou (tamanho ou data de modificação). O arquivo loader dele pode carregar, antes de a geração começar, classes que o cache ainda não conhece: elas são carregadas sem compilação nesse momento e compiladas pela geração.
PARTIAL_REFLECTION
Seção intitulada “PARTIAL_REFLECTION”Compila uma classe cuja classe pai, interface ou trait não pode ser localizada: uma declarada por código gerado em tempo de execução, por um class_alias() ou num arquivo fora do autoloader do Composer. A classe é avaliada e compilada com os próprios métodos e propriedades e com os dos ancestrais disponíveis. Membros herdados de um ancestral ausente não são interceptados.
Sem a flag, essa classe falha na compilação. Ligue a flag quando encontrar essa falha.
Regras de funções e de inicialização não precisam de flag
Seção intitulada “Regras de funções e de inicialização não precisam de flag”O framework habilita o mecanismo dessas matching rules (regras de correspondência) a partir das behavior classes registradas, inclusive as registradas como lazy. Você não define nada em features:
- Uma regra
execution(Namespace\function(*))adiciona proxies de funções aos namespaces correspondentes. - Uma regra
initialization(...)liga a reescrita das expressõesnew Foo(...)nos arquivos compilados. Enquanto houver uma registrada, todonewreescrito passa pelo interceptor, então limite essas regras ao código que precisa delas.
A sintaxe das matching rules está em Behaviors e matching rules.
Behavior classes a partir do container da aplicação
Seção intitulada “Behavior classes a partir do container da aplicação”O container do kernel é um container PSR-11 (Go\Core\AspectContainer estende Psr\Container\ContainerInterface). Ele pode delegar ao container da sua aplicação: Symfony, Laravel, PHP-DI ou qualquer outro container PSR-11. get(), getService() e has() recorrem ao delegate para ids que não estão registrados no container do kernel.
O kernel é inicializado antes de a aplicação montar o container dela. Por isso você registra as behavior classes normalmente e deixa que resolvam suas dependências de forma lazy:
protected function configureAop(AspectContainer $container): void{ // Runs when one of its behaviors first runs, after the application container is attached $container->addLazyService( MonitorAspect::class, static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)), ); // or take the whole behavior class from the application container, by the id it has there // $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));}Assim que o container da aplicação existir, por exemplo logo depois que o kernel do seu framework inicializar, ligue-o:
ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);A compile step (etapa de compilação) e o aquecimento do cache só precisam da behavior class em si. Eles rodam antes de setDelegate(), inclusive em vendor/bin/aspect, e nunca criam uma instância dela. A factory roda quando um dos behaviors (comportamentos) dela roda pela primeira vez; uma dependência que ainda estiver faltando nesse momento lança ServiceNotFoundException.
As bridges para Symfony, Laravel e Yii 3 estão em Integrações.
Regras para factories de behavior classes
Seção intitulada “Regras para factories de behavior classes”- Uma factory nunca pede ao container do kernel o próprio id. Esse id resolve para a behavior class que está sendo construída. Pegue a instância do container da aplicação pelo id que ela tem lá, ou construa-a a partir das dependências.
- Behavior classes nunca são descobertas no delegate. Um container PSR-11 não pode ser inspecionado: não há forma padrão de buscar serviços por interface ou por tag. Toda behavior class é registrada em
configureAop(). Uma bridge para um framework específico pode coletar serviços por tag ou interface no container dele e registrá-los comaddLazyService(). - A compile step nunca cria uma instância de behavior class. Ela lê a behavior class, e o código gerado se refere a cada behavior pelo nome da classe e do método. Toda behavior class, inclusive uma sem propriedades de instância (que o PHP não consegue tornar lazy), é criada pela sua factory quando um dos seus behaviors roda pela primeira vez, depois que o container da aplicação é ligado.
- Criar uma behavior class não pode rodar um dos próprios behaviors dela. Se a behavior class depende de um serviço cuja construção um dos seus behaviors intercepta (o construtor do serviço, ou um método que o construtor chama), esse behavior rodaria numa instância que ainda não existe. O interceptor informa isso com uma
AspectCircularReferenceExceptionque cita a behavior class, a chamada interceptada e as chamadas desde a criação até o behavior. Injete a dependência de forma lazy (um serviço lazy, uma closure ou um service locator) ou restrinja a matching rule para que a behavior class não intercepte a criação das próprias dependências.
Classe de container personalizada
Seção intitulada “Classe de container personalizada”Para substituir o container do kernel, passe sua classe como containerClass. Ela precisa implementar Go\Core\AspectContainer, ou seja, get() e has() do PSR-11, mais setDelegate(). Um id desconhecido lança ServiceNotFoundException, que implementa Psr\Container\NotFoundExceptionInterface.
Modo de desenvolvimento e modo de produção
Seção intitulada “Modo de desenvolvimento e modo de produção”A opção debug alterna entre dois modos. Suas behavior classes e matching rules são as mesmas nos dois.
'debug' => true |
'debug' => false |
|
|---|---|---|
| Carregamento de classes | Toda classe e todo include passam pelo stream filter de compilação. |
As classes compiladas vêm do cache pelo class map do Composer. |
| Fonte, behavior class ou arquivo do kernel alterado | Compilado de novo na próxima requisição. | O cache é servido como está. |
| Regeração do cache | Não é necessária. | A cada deploy, com cache:warmup:aop. |
| Use para | Desenvolvimento local. | Produção. Adicione Features::PREBUILT_CACHE. |
Em desenvolvimento não há etapa de build: edite uma classe ou um behavior, recarregue, e o framework recompila o que mudou. Os breakpoints funcionam no seu código original.
Em produção, o framework entrega o class map do cache ao Composer, e o parser e os transformers não são carregados em requisições mornas. Com PREBUILT_CACHE por cima, uma requisição também pula todas as verificações de arquivos-fonte e de atualidade do cache. Como ajustar isso ainda mais (OPcache, preloading, containers) está em Produção e desempenho.
O diretório de cache
Seção intitulada “O diretório de cache”cacheDir é a única opção obrigatória. O diretório guarda:
- os fontes compilados: o corpo original de cada classe como uma trait
<Class>OriginalTrait, no caminho relativo do seu arquivo-fonte; - os proxies, ao lado dos fontes compilados, com o nome original da classe;
- os caches de advisors das suas behavior classes, como arquivos PHP comuns ao lado dos fontes compilados;
- os metadados, incluindo
_include.cache, o class map entregue ao Composer; _preload.php, quando você gera o cache comcache:warmup:aop --preload.
O que você precisa saber:
- Ele espelha
appDir. Os caminhos no cache são relativos à raiz da aplicação, e os caminhos dentro dos metadados são guardados relativos a__DIR__, então o cache continua válido quando o diretório da aplicação muda de lugar. - Ele nunca é compilado. O diretório de cache é sempre excluído, não importa o que você coloque em
excludePaths. - As permissões vêm de
cacheFileMode. O padrão é0770menos a umask. Gere o cache como o usuário que atende as requisições, ou para ele. - Apague-o ao atualizar a partir da 3.x. Nenhum arquivo de cache da 3.x é reaproveitado, e com
PREBUILT_CACHEum cache gerado por outra versão do framework é rejeitado.
O console
Seção intitulada “O console”vendor/bin/aspect cache:warmup:aop public/index.phpvendor/bin/aspect precisa de symfony/console (^7.4 || ^8.0). Instale-o com o Composer se a sua aplicação ainda não o tiver.
Todo comando recebe o caminho do arquivo que inicializa o seu kernel, normalmente o front controller ou um arquivo de bootstrap. Esse arquivo é executado, então o comando enxerga o kernel com as mesmas opções da sua aplicação. Dentro de uma aplicação que já inicializou o kernel (o console de uma integração com framework, em que os comandos são registrados como serviços), você omite o argumento: os comandos usam o kernel do processo.
Todo comando retorna Command::SUCCESS ou Command::FAILURE. Verifique o código de saída nos scripts.
| Comando | Finalidade |
|---|---|
cache:warmup:aop |
Compila para o cache todo arquivo abaixo dos include paths. |
cache:warmup:opcache |
Pré-aquece o opcache.file_cache com o cache do framework e o que uma requisição carrega. |
debug:aspect |
Lista as behavior classes registradas e seus behaviors. |
debug:advisor |
Lista os advisors (cada behavior com sua matching rule), ou as chamadas interceptadas que um advisor seleciona. |
debug:weaving |
Aquece o cache duas vezes e informa os proxies gerados de forma diferente. |
cache:warmup:aop
Seção intitulada “cache:warmup:aop”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8O comando compila todo arquivo abaixo de includePaths (menos excludePaths) e grava os arquivos compilados, os proxies, os caches de advisors e os metadados. Ele mostra uma barra de progresso. Informa no stderr todo arquivo que não pode ser compilado e sai com código diferente de zero, então um script de deploy ou um docker build para ali em vez de publicar um cache incompleto.
| Opção | Padrão | Finalidade |
|---|---|---|
--workers=N |
1 (compila no processo do comando) |
Compila em N processos worker em paralelo. Use o número de CPUs. |
--cached-files=N |
a opção do kernel parsedFilesLimit, 100 |
Quantidade de arquivos parseados que cada processo mantém em memória. |
--fail-fast |
desligada | Para no primeiro arquivo que não pode ser compilado. |
--cache-dir=DIR |
o cacheDir do kernel |
Gera o cache em outro diretório, do zero, enquanto o kernel e os workers continuam usando o seu. |
--preload[=FILE] |
desligada | Grava também o script de opcache.preload do cache: _preload.php no diretório de cache, ou FILE. |
-v |
desligada | Imprime cada arquivo em vez de só a barra de progresso. |
Observações sobre as opções:
--cache-diré como um deploy prepara o cache da próxima release ao lado da que está rodando e depois o troca de forma atômica, por exemplo trocando um symlink. Um cache gerado assim é completo e independente de localização, mesmo quando um kernel de produção o gera com o próprio cache aquecido: o compilador sempre lê os fontes originais, nunca os arquivos compilados que o Composer serve.--preloadna forma sem valor precisa vir depois do argumento do loader; caso contrário, toma o loader como valor. O script vincula, quando o PHP inicia, toda classe compilada e toda classe não transformada que o cache conhece; classes com um behavior na inicialização estática ficam por conta do autoloader. Ele não contém nenhum caminho absoluto e lista as classes exatamente deste cache, então você o gera de novo junto com o cache. A configuração do preloading está em Produção e desempenho.- Sobre um diretório existente, o comando compila de novo todo arquivo cujo fonte mudou (tamanho ou data de modificação) e mantém os outros, também com
PREBUILT_CACHE. Comece de um diretório vazio quando quiser que o cache contenha exatamente a release atual.
cache:warmup:opcache
Seção intitulada “cache:warmup:opcache”vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.phpCompila para o opcache.file_cache o que uma requisição de produção carrega: o cache do framework, o class map e os arquivos carregados automaticamente pelo Composer, os fontes não transformados, o loader e os pontos de entrada. Um novo processo master do PHP-FPM ou de CLI passa então a ler scripts compilados do disco em vez de compilá-los.
| Opção | Finalidade |
|---|---|
--file-cache=DIR |
O diretório do opcache.file_cache. Precisa ser o mesmo configurado. |
--entry=FILE |
Um ponto de entrada a compilar. Repita para vários arquivos. |
Os scripts compilados só são gravados em disco por um processo iniciado com -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR. Se o comando rodar sem essas opções, ele imprime o comando exato a executar.
O file cache pertence ao build do PHP e aos caminhos absolutos dos arquivos. Rode o comando na imagem final, depois de cache:warmup:aop, com o binário PHP que atende as requisições. O cache do framework, o loader e os pontos de entrada precisam compilar, ou o comando falha; arquivos do class map do Composer que não compilam são listados e ignorados.
debug:aspect
Seção intitulada “debug:aspect”vendor/bin/aspect debug:aspect public/index.phpLista as behavior classes registradas e seus behaviors. Também aceita a opção --aspect=....
debug:advisor
Seção intitulada “debug:advisor”vendor/bin/aspect debug:advisor public/index.phpLista os advisors. Com --advisor=..., mostra as chamadas interceptadas que esse advisor seleciona, o que diz se a sua matching rule pega os métodos que você espera.
debug:weaving
Seção intitulada “debug:weaving”vendor/bin/aspect debug:weaving public/index.phpAquece o cache duas vezes e informa os proxies gerados de forma diferente entre as duas execuções. Uma diferença aponta para uma behavior class não determinística.
Noções básicas de deploy
Seção intitulada “Noções básicas de deploy”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- Limpe o diretório de cache.
- Faça o aquecimento do cache com
cache:warmup:aop. O comando falha quando um arquivo não pode ser compilado, então o deploy para em vez de publicar um cache incompleto. Projetos grandes compilam mais rápido em paralelo com--workers. - Rode com
'debug' => falseeFeatures::PREBUILT_CACHE.
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);Gere o cache de novo sempre que o código, as behavior classes, as opções do kernel ou o composer.lock mudarem. Na prática, isso significa a cada deploy. O modo de desenvolvimento não precisa de regerações.
Ajuste do OPcache, preloading, flags do autoloader do Composer e geração do cache numa imagem Docker estão em Produção e desempenho. A atualização a partir da 3.x, incluindo a mudança de formato do cache, está em Limitações e atualização.
© 2026 Alexander Lisachenko
