Pular para o conteúdo
Documentação

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.

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):

app/ApplicationAspectKernel.php
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:

public/index.php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([
'debug' => false,
'appDir' => __DIR__ . '/..',
'cacheDir' => __DIR__ . '/../var/cache/aop',
'includePaths' => [__DIR__ . '/../src'],
]);

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.

As feature flags são constantes da classe final Go\Aop\Features. Combine-as com |:

public/index.php
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.

Passa include e require dos arquivos compilados pelo compilador. Use para código legado que não é carregado pelo Composer.

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.

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ões new Foo(...) nos arquivos compilados. Enquanto houver uma registrada, todo new reescrito 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:

app/ApplicationAspectKernel.php
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.

  • 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 com addLazyService().
  • 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 AspectCircularReferenceException que 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.

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.

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.

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 com cache: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 é 0770 menos 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_CACHE um cache gerado por outra versão do framework é rejeitado.
Janela do terminal
vendor/bin/aspect cache:warmup:aop public/index.php

vendor/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.
Janela do terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8

O 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.
  • --preload na 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.
Janela do terminal
vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php

Compila 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.

Janela do terminal
vendor/bin/aspect debug:aspect public/index.php

Lista as behavior classes registradas e seus behaviors. Também aceita a opção --aspect=....

Janela do terminal
vendor/bin/aspect debug:advisor public/index.php

Lista 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.

Janela do terminal
vendor/bin/aspect debug:weaving public/index.php

Aquece 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.

Janela do terminal
rm -rf var/cache/aop
vendor/bin/aspect cache:warmup:aop public/index.php --workers=8
  1. Limpe o diretório de cache.
  2. 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.
  3. Rode com 'debug' => false e Features::PREBUILT_CACHE.
public/index.php
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