Produção e desempenho
Quanto o framework custa em tempo de execução e como gerar, ajustar e publicar o cache para que a produção pague apenas pelas chamadas que têm behaviors.
Traduzido do inglês. A página em inglês é a referência. Ler o original
O framework compila suas classes junto com os behaviors (comportamentos) uma única vez e guarda o resultado como arquivos PHP comuns. A partir daí, esses arquivos são servidos como qualquer outro código: o OPcache os mantém em cache, o Composer os carrega, e nenhum parser, reflection ou eval() roda durante a requisição. Uma requisição de produção com o cache aquecido lê um arquivo de metadados, entrega as classes geradas ao Composer e paga apenas pelas chamadas que de fato são interceptadas. Métodos e propriedades sem behaviors não custam nada.
Esta página traz os números medidos, explica de onde vem o custo e mostra como publicar o cache: aquecimento do cache no deploy, OPcache, Composer, Docker e Kubernetes. As opções do kernel estão descritas em Configuração e CLI. Um resumo visual está na página do recurso Performance.
Custos medidos
Seção intitulada “Custos medidos”Todos os números desta página vêm do docs/performance.md upstream do goaop/framework. Eles foram medidos em uma única máquina, então leia-os como proporções entre os modos. São as proporções que se mantêm em outras máquinas.
Configuração do benchmark
Seção intitulada “Configuração do benchmark”- Uma pequena aplicação de loja: cerca de 250 arquivos abaixo dos include paths (94 classes compiladas), 120 classes de biblioteca fora deles e 6 behavior classes (classes de comportamento) com
#[Before],#[Around],#[AfterThrowing]e behaviors de propriedade. - Uma requisição faz 50 pedidos. Isso dá ~2.600 chamadas de método interceptadas e ~950 acessos a propriedades interceptados.
- PHP 8.5.12 NTS, 4 CPUs, OPcache em memória compartilhada,
opcache.jit=disable,opcache.file_update_protection=0.
O método completo está em Reproduzindo os benchmarks, mais abaixo.
Tempo de requisição por modo
Seção intitulada “Tempo de requisição por modo”Os três estados do cache:
- quente (hot): cache compilado presente, OPcache preenchido. O estado estável de um worker de produção.
- morno (warm): cache compilado presente, OPcache vazio. Um PHP-FPM recém-iniciado ou um pod novo.
- frio (cold): nada em cache ainda. A primeira requisição compila cada classe que carrega.
| Modo | quente | morno | Pico de memória (quente) |
|---|---|---|---|
debug => false + PREBUILT_CACHE |
5,4 ms | 59 ms | 1,3 MB |
debug => false |
5,5 ms | 62 ms | 1,3 MB |
debug => true |
13,0 ms | 63 ms | 2,2 MB |
| A mesma aplicação sem o framework (os behaviors não rodam) | 2,1 ms | 36 ms | 0,7 MB |
- ~3.500 interceptações com corpos de behavior reais (logging, consultas ao cache, timers) acrescentam ~3,3 ms à requisição. O boot do kernel responde por ~0,15 ms disso.
- Uma chamada interceptada custa cerca de um terço de microssegundo, e cada behavior adicional nela, ~70 ns.
- O cache inteiro é gerado em menos de meio segundo com
cache:warmup:aop. Uma aplicação de 2.000 arquivos leva 1,1 s com 4 workers. - Os containers já começam quentes. Com um file cache do OPcache pré-aquecido, a primeira requisição de um PHP-FPM novo leva 19 ms em vez de 71 ms. Com preloading por cima, leva 10 ms, o mesmo que a aplicação pura sem o framework (9 ms).
Custo por chamada
Seção intitulada “Custo por chamada”Estes números usam behaviors vazios, então medem só o trabalho do próprio framework: o call context (contexto de chamada), a cadeia de interceptores e a chamada do método original.
| Chamada | Overhead por chamada |
|---|---|
| Método ou propriedade sem behavior em uma classe compilada | 0 |
Método com um #[Before] ou #[Around] |
~0,33 µs |
Método com três #[Around] |
~0,48 µs |
Método estático com um #[Around] |
~0,34 µs |
Leitura de propriedade com um #[Around] |
~0,22 µs |
Escrita de propriedade com um #[Around] |
~0,26 µs |
Um milhão de chamadas interceptadas custa cerca de um terço de segundo. Uma requisição típica, com algumas centenas de interceptações, paga uma fração de milissegundo.
Processos CLI
Seção intitulada “Processos CLI”Todo processo CLI começa com o OPcache vazio. Um opcache.file_cache pré-aquecido faz comandos de vida curta iniciarem quase tão rápido quanto uma requisição web quente.
| Tempo de script por processo | OPcache desligado | OPcache ligado (só memória) | opcache.file_cache, pré-aquecido |
|---|---|---|---|
PREBUILT_CACHE |
33 ms | 69 ms | 21 ms |
debug => false |
30 ms | 69 ms | 22 ms |
| Sem o framework | 19 ms | 34 ms | 10 ms |
O que custa o quê
Seção intitulada “O que custa o quê”Membros sem behaviors
Seção intitulada “Membros sem behaviors”O proxy sobrescreve apenas os membros que têm behaviors. Todos os outros métodos e propriedades são o seu código original e rodam em velocidade máxima: o overhead é 0. Classes que nenhuma matching rule (regra de correspondência) seleciona nem chegam a ser compiladas.
Chamadas interceptadas e behaviors empilhados
Seção intitulada “Chamadas interceptadas e behaviors empilhados”Cada método interceptado declara um call context estático:
static $__joinPoint = InterceptorInjector::forMethod(...)O call context e sua lista de interceptores são montados na primeira chamada. Cada chamada seguinte é um único $__joinPoint->__invoke($this, [$args]). Essa lista guarda first-class callables que apontam direto para os métodos das suas behavior classes, então não há busca de behaviors, nem reflection, nem __call().
O primeiro behavior em um método custa ~0,33 µs. Cada behavior adicional acrescenta ~70 ns, então três behaviors #[Around] custam ~0,48 µs. Um método estático com um #[Around] custa ~0,34 µs.
A reflection para behaviors (getMethod(), getField()) só é criada quando um behavior a pede.
Acesso a propriedades
Seção intitulada “Acesso a propriedades”A interceptação de propriedades compila para hooks get e set nativos do PHP 8.4 no proxy. Não há mágica de __get() ou __set() nem reflection por acesso. Uma leitura de propriedade com um #[Around] custa ~0,22 µs; uma escrita, ~0,26 µs.
Boot do kernel
Seção intitulada “Boot do kernel”O boot do kernel leva ~0,15 ms no benchmark. Os serviços do framework, os transformers e as suas behavior classes são registrados como factories, uma escrita em array cada. Nada é carregado pelo autoloader, refletido ou instanciado no boot, então uma requisição morna nunca carrega o parser, a gramática das matching rules, o matcher de behaviors nem os transformers.
- O índice do cache (
CachePathManager) é o único serviço construído eminit(), porque o autoloader lê o class map imediatamente. - As behavior classes são instanciadas na primeira chamada de um de seus behaviors, como lazy objects nativos do PHP 8.4. A compile step (etapa de compilação) e o aquecimento do cache nunca instanciam uma behavior class; apenas a leem.
- A produção não arma nenhum listener de registro. O modo debug acompanha mudanças nos arquivos das behavior classes por meio de um listener que resolve os arquivos via Composer sem carregar as classes.
- A tabela de parsing da gramática das matching rules é PHP gerado, e as regras só são analisadas no primeiro uso.
Inicializações fria e morna
Seção intitulada “Inicializações fria e morna”Uma requisição morna (cache compilado presente, OPcache vazio) leva 59 ms com PREBUILT_CACHE, contra 36 ms da aplicação pura. Você a encurta com um opcache.file_cache pré-aquecido e preloading; veja Docker e Kubernetes.
Uma requisição fria compila cada classe que carrega. Com um cache gerado no deploy e PREBUILT_CACHE, uma requisição de produção nunca compila.
Tempo de compilação
Seção intitulada “Tempo de compilação”A compilação acontece uma vez, no deploy.
- O cache da aplicação do benchmark é gerado em menos de meio segundo.
- Uma aplicação de 2.047 arquivos levou 2,2 s com um worker e 1,1 s com 4 workers em 4 CPUs.
- Cada arquivo analisado mantido em memória durante a compilação ocupa ~0,2 MB. A opção de kernel
parsedFilesLimit(padrão100) limita quantos são mantidos.
O que mantém a compilação rápida:
- O caminho de cache hit não analisa nada. Um registro atualizado é servido como conteúdo em cache antes que qualquer transformer exista. O stream filter e a cadeia de transformers só são montados no primeiro miss.
- Todas as regras de reescrita compartilham uma única travessia da árvore sintática. Uma regra cujo marcador no fonte não aparece no arquivo é pulada, e um arquivo sem nenhuma regra aplicável nem chega a ser percorrido. É o caso da maioria dos arquivos.
- São as suas behavior classes que ligam a maquinaria. Expressões
newsó são reescritas enquanto houver uma regrainitialization(...)registrada. Proxies de função só existem para regras de função. - A verificação de behavior class, que reflete todos os ancestrais, só roda para classes que têm behaviors.
- Os behaviors de uma behavior class ficam em cache como um arquivo PHP simples de expressões estáticas de construtor, cerca de duas vezes mais rápido de carregar que
unserialize(). - Os proxies são montados como árvores sintáticas e impressos uma única vez (−43% no tempo de compilação). A trait gerada é produzida por edições de tokens que preservam os seus números de linha para o Xdebug.
O que uma requisição de produção faz
Seção intitulada “O que uma requisição de produção faz”| Etapa | debug => false (+ PREBUILT_CACHE) |
debug => true |
|---|---|---|
init() do kernel |
opções, container, factories de serviço (nada é instanciado) | o mesmo, mais os arquivos do kernel e das behavior classes acompanhados para detectar mudanças |
_include.cache (class map, skip set) |
um include, servido pelo OPcache, sem stat() do diretório de cache |
o mesmo |
| Classe compilada | class map do Composer → arquivo em cache, vindo do OPcache | verificação de atualização, depois o stream filter, para que os breakpoints do Xdebug e as constantes mágicas apontem para os seus arquivos originais |
| Classe não transformada abaixo dos include paths | skip set → o arquivo original, vindo do OPcache | verificação de atualização → o arquivo original, vindo do OPcache |
| Parser, transformers, stream filter | nunca carregados | stream filter registrado, nenhum transformer montado |
| Um arquivo-fonte alterado | o cache gerado no deploy é servido como está | recompilado na próxima requisição |
Chamadas ao sistema de arquivos em uma requisição quente, contadas pelo profiler:
| Chamada | PREBUILT_CACHE |
debug => false |
debug => true |
Sem o framework |
|---|---|---|---|---|
filemtime / filesize |
0 | 0 | 323 / 239 | 0 |
file_get_contents |
0 | 0 | 94 | 0 |
file_exists (PSR-4 do Composer) |
307 | 307 | 412 | 357 |
Uma requisição de produção não verifica nenhum arquivo-fonte. Ela faz até menos buscas no Composer que a aplicação pura, porque as classes geradas vêm direto do class map. Um class map otimizado do Composer elimina as buscas restantes; veja Autoloader do Composer.
Mais dois detalhes do índice de runtime:
_include.cacheguarda apenas o que uma requisição precisa: o class map, o skip set e o include map. Os registros completos do build ficam em_transformation.cache, que a produção nunca lê.- Os dois arquivos de metadados são arrays gerados com
var_export(), com caminhos relativos a__DIR__. O OPcache os mantém imutáveis na memória compartilhada, então incluí-los não copia nada, e o cache continua válido quando o diretório da aplicação muda de lugar.
O modo debug é feito para desenvolvimento. Suas requisições quentes levam ~13 ms no benchmark; as de produção, ~5,5 ms. O modo debug ainda inclui um arquivo não transformado e atualizado pelo seu caminho original, então o OPcache o mantém em cache (~38 µs → ~10 µs por arquivo, requisições de debug 27–40% mais rápidas).
Checklist de produção
Seção intitulada “Checklist de produção”-
Defina
'debug' => falsee'features' => Features::PREBUILT_CACHE. -
Gere o cache no deploy ou no build da imagem com
cache:warmup:aop. -
Mantenha
includePathsrestrito: o seusrc/, não ovendor/. -
Registre as behavior classes com
addLazyService(). -
Instale as dependências com
composer install --no-dev --classmap-authoritative. -
Rode o OPcache com
opcache.validate_timestamps=0e com memória e slots de arquivo suficientes para os arquivos gerados. -
Em containers, gere o cache dentro da imagem e acrescente um
opcache.file_cachepré-aquecido ou preloading.
O kernel de produção:
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);Gerando o cache no deploy
Seção intitulada “Gerando o cache no deploy”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc)Comece de um diretório vazio, para que o cache contenha exatamente a release atual. O argumento é o arquivo que inicializa o seu kernel: o front controller (controlador frontal) ou um arquivo de bootstrap. O comando o executa, então o kernel inicia com as mesmas opções que em produção.
O comando:
- compila todos os arquivos abaixo de
includePaths(menosexcludePaths) e grava os arquivos gerados, os proxies, os caches das behavior classes e os dois arquivos de metadados; - reporta no stderr cada arquivo que não pode ser compilado e sai com código diferente de zero, para que um script de deploy ou um
docker buildpare ali em vez de publicar um cache incompleto.
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 debug dispensa rebuilds: ele recompila sozinho as classes, as behavior classes e os arquivos do kernel que mudaram.
A assinatura completa do comando:
cache:warmup:aop [<loader>] [--fail-fast] [--workers=N] [--cached-files=N] [--cache-dir=DIR] [--preload[=FILE]]Dentro de uma aplicação que já inicializou o seu kernel (o console de uma integração com framework), o argumento loader é omitido e o comando usa o kernel do próprio processo. Veja Integrações.
Workers
Seção intitulada “Workers”--workers=N compila em N processos worker, dos maiores arquivos para os menores. O padrão é 1, que compila no próprio processo do comando. Use o número de CPUs. O coordenador grava os metadados uma vez, e cada processo mantém um número limitado de árvores sintáticas em memória.
--cached-files=N define esse limite por processo. O padrão é a opção de kernel parsedFilesLimit (100). Mais arquivos em cache significam menos re-parsing; menos arquivos, menos memória. Acrescente -v para listar cada arquivo em vez da barra de progresso.
Gerando ao lado da release em execução
Seção intitulada “Gerando ao lado da release em execução”--cache-dir=DIR gera o cache em outro diretório, do zero, enquanto o kernel continua servindo a partir do seu. Use-o para preparar o cache da próxima release ao lado da que está rodando e trocá-lo de forma atômica, por exemplo com uma troca de 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 das classes que reflete, nunca os arquivos gerados que o Composer serve em produção.
Executado sobre um diretório existente, o comando recompila cada arquivo cujo fonte mudou (tamanho ou data de modificação) e mantém os demais. Isso vale também com PREBUILT_CACHE: só as requisições confiam no cache como ele está; o comando de aquecimento, não.
PREBUILT_CACHE e sistemas de arquivos somente leitura
Seção intitulada “PREBUILT_CACHE e sistemas de arquivos somente leitura”Features::PREBUILT_CACHE faz as requisições confiarem totalmente no cache gerado no deploy. Ele pula:
- as sondagens do diretório de cache e da permissão de escrita;
- as comparações de
filemtimedos fontes; - as verificações dos recursos acompanhados;
- as verificações de atualização dos caches das behavior classes.
Uma requisição nunca compila e nunca grava no diretório de cache, então funciona em sistemas de arquivos somente leitura. Por isso o cache precisa estar completo. Uma classe ou um arquivo incluído abaixo dos include paths sem registro no cache, ou um registro cujo arquivo em cache sumiu, faz a requisição falhar com uma WeavingException antes que qualquer coisa seja compilada. Isso inclui um arquivo adicionado depois do build, mesmo um que não precise de compilação.
Arquivos que o compilador nunca processa são carregados como estão: arquivos fora dos include paths, arquivos excluídos e arquivos que não são .php, como um template incluído.
Cada arquivo de cache é gravado em um arquivo temporário único, renomeado para o lugar definitivo e então invalidado no OPcache. Requisições concorrentes nunca veem um arquivo gravado pela metade, nenhum lock é necessário, e processos que gravam os metadados ao mesmo tempo mesclam seus registros.
Autoloader do Composer
Seção intitulada “Autoloader do Composer”Classes que não são compiladas são encontradas pelo Composer como de costume. Com um class map otimizado, cada busca é um acesso a array em vez de um file_exists(), e o class map das classes geradas é mesclado a ele com addClassMap(). Classes geradas e não transformadas passam então a ser servidas do mesmo jeito.
Requisição quente do benchmark:
| Autoloader | PREBUILT_CACHE |
debug => false |
Sem o framework |
|---|---|---|---|
PSR-4 (composer install) |
5,5 ms | 6,7 ms | 2,3 ms |
--optimize-autoloader (-o) |
5,2 ms | 5,0 ms | 1,6 ms |
--classmap-authoritative (-a) |
4,8 ms | 4,6 ms | 1,9 ms |
Com --classmap-authoritative, o Composer nunca procura uma classe fora do class map. Rode dump-autoload depois de qualquer geração de código e antes do aquecimento.
Ajuste do OPcache
Seção intitulada “Ajuste do OPcache”Cada classe compilada vira dois arquivos em cache: o seu corpo original como trait, e o proxy. Cada behavior class ganha um arquivo de cache próprio. Dê espaço ao OPcache para todos eles.
| Configuração | Valor em produção | Por quê |
|---|---|---|
opcache.enable |
1 |
O código gerado é PHP comum, mantido em cache como o resto da aplicação. |
opcache.memory_consumption |
128–256 (MB) |
Confira opcache_get_status()['memory_usage'] sob carga. |
opcache.interned_strings_buffer |
16–32 (MB) |
Proxies e traits gerados compartilham nomes de classes e métodos. |
opcache.max_accelerated_files |
≥ 2 × os arquivos PHP da aplicação e do vendor/ |
Cada classe compilada acrescenta um arquivo. |
opcache.validate_timestamps |
0 |
Releases imutáveis e containers: nenhum stat por include. Recarregue o PHP-FPM depois de um deploy. |
opcache.file_update_protection |
0 |
O framework grava cada arquivo de cache de forma atômica, então o OPcache pode guardar arquivos recém-gerados imediatamente, em vez de esperar 2 segundos (o padrão). |
opcache.file_cache |
um diretório | Um cache de segundo nível em disco: um novo master do PHP-FPM ou processo CLI carrega scripts já compilados em vez de compilá-los. Pré-aqueça-o no build. |
opcache.preload |
opcional | Faz o link das classes geradas uma única vez, na inicialização do servidor; veja Preloading. |
realpath_cache_size / realpath_cache_ttl |
4096K / 600 |
Com validate_timestamps=1: menos buscas de caminho por include. |
O código gerado é PHP comum, compilado pelo JIT como o resto da aplicação. Uma requisição web típica passa seu tempo em muitas chamadas curtas, onde o JIT ganha pouco, então meça antes de ativá-lo.
Preloading
Seção intitulada “Preloading”Os arquivos gerados são declarações de classe comuns, então um cache pré-gerado pode ser pré-carregado. --preload grava o script opcache.preload do cache que gera: _preload.php no diretório de cache, ou o arquivo indicado em --preload=FILE.
vendor/bin/aspect cache:warmup:aop public/index.php --workers=$(nproc) --preloadopcache.preload=/app/var/cache/aop/_preload.phpopcache.preload_user=www-dataO --preload sem valor precisa vir depois do argumento loader; caso contrário, ele toma o loader como seu valor.
Quando o PHP-FPM inicia, o script faz require do autoloader do Composer, entrega a ele o class map das classes geradas e faz o link, no OPcache, de cada classe compilada, do seu proxy e de cada classe não transformada conhecida pelo cache.
- Os autoloads
filesdo Composer (funções auxiliares, bootstraps de polyfill) não são pré-carregados. As requisições os incluem como antes. - O script não contém nenhum caminho absoluto. Tudo é localizado via
__DIR__, como nos arquivos de metadados, então um cache movido junto com a aplicação continua válido. - Ele lista as classes exatamente do cache com que foi gerado. Gere-o de novo junto com o cache.
- Uma classe que não pode ser linkada durante o preloading (falta uma dependência opcional) é registrada no log de erros e deixada para o autoloader da requisição.
- Uma classe com um behavior na sua inicialização estática também fica para o autoloader: o behavior precisa do kernel, então quem a carrega é a requisição.
O kernel continua sendo inicializado a cada requisição; o autoloader simplesmente nunca precisa carregar as classes pré-carregadas. No benchmark, o preloading reduziu os arquivos incluídos por requisição de 517 para 174, a requisição quente de 5,2 ms para 4,9 ms, e a primeira requisição após a inicialização do servidor de 71 ms para 24 ms (10 ms junto com um file cache pré-aquecido).
As classes pré-carregadas só mudam com um restart do PHP-FPM, que é como o deploy de containers funciona de qualquer forma. Nada é pré-carregado no CLI, a menos que opcache.enable_cli=1 esteja definido.
Docker e Kubernetes
Seção intitulada “Docker e Kubernetes”Gere o cache do framework dentro da imagem. Assim, cada container inicia com um cache completo e somente leitura, cada réplica serve exatamente o mesmo código gerado, e nenhum pod jamais compila. O shop demo traz essa configuração como uma imagem funcional.
Dockerfile
Seção intitulada “Dockerfile”FROM php:8.5-fpm
# OPcache is part of PHP 8.5, no docker-php-ext-install neededCOPY docker/opcache.ini /usr/local/etc/php/conf.d/opcache.iniCOPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /appCOPY composer.json composer.lock ./RUN composer install --no-dev --no-scripts --no-autoloader --prefer-distCOPY . .RUN composer dump-autoload --no-dev --classmap-authoritative
# 1. The framework's cache: generated classes, proxies, behavior caches, metadata, owned by the user that serves it# (cache files get the `cacheFileMode` kernel option, by default 0770 minus the umask)RUN rm -rf var/cache/aop \ && php vendor/bin/aspect cache:warmup:aop public/index.php --workers="$(nproc)" --preload \ && chown -R www-data:www-data var/cache/aop \ && chmod -R a-w var/cache/aop
# 2. The OPcache file cache: a new PHP-FPM master loads compiled scripts instead of compiling them.# Built in the final image, as the file cache belongs to this PHP build and these paths.RUN mkdir -p /var/cache/opcache \ && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=/var/cache/opcache \ vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.php \ && chown -R www-data /var/cache/opcache
USER www-datacache:warmup:opcache compila o que a aplicação carrega: o cache do framework (arquivos gerados, proxies, caches das behavior classes e metadados), o class map e os arquivos carregados automaticamente pelo Composer, os fontes abaixo dos include paths que não são compilados, o arquivo loader e os entry points indicados com --entry.
- Scripts compilados só são gravados em disco por um processo iniciado com
opcache.enable_cli=1,opcache.file_cache_only=1eopcache.file_cache=DIR. Essas configurações não podem ser definidas em tempo de execução. O comando as verifica, e confere também se--file-cache=DIRé o diretório configurado; caso contrário, imprime o comando exato a executar. - O cache do framework, o loader e os entry points precisam compilar, senão o comando falha. Um arquivo do class map do Composer que não compila (um stub de teste de um pacote do vendor escrito para um PHP mais novo) é listado e pulado; o PHP registra o erro de compilação no log.
- Rode-o depois de
cache:warmup:aop, na imagem final, com o binário PHP que atende as requisições. O file cache é indexado pelo build do PHP e pelos caminhos absolutos dos arquivos.
opcache.ini
Seção intitulada “opcache.ini”opcache.enable=1opcache.memory_consumption=192opcache.interned_strings_buffer=32opcache.max_accelerated_files=50000opcache.validate_timestamps=0opcache.file_cache=/var/cache/opcacheopcache.file_cache_consistency_checks=0; PHP 8.5: the primed file cache is only read at runtime, also on a read-only root file systemopcache.file_cache_read_only=1; required on PHP 8.5.11 / 8.5.12, see "JIT"opcache.jit=disable; optional, see "Preloading" (written by cache:warmup:aop --preload); opcache.preload=/app/var/cache/aop/_preload.php; opcache.preload_user=www-dataO kernel da imagem é o kernel de produção do checklist: debug => false, includePaths limitado a src/ e Features::PREBUILT_CACHE.
No benchmark, essa configuração serve a primeira requisição de um servidor novo em 19 ms com o file cache, e em 10 ms com o file cache mais preloading, contra 71 ms sem nenhum dos dois. Os pods são rápidos desde a primeira requisição.
Kubernetes
Seção intitulada “Kubernetes”- Sistema de arquivos raiz somente leitura (
readOnlyRootFilesystem: true).PREBUILT_CACHElê o cache gerado dentro da imagem e não grava nada em tempo de execução. - Uma imagem, um cache. Mantenha o cache dentro da imagem, e não em um volume compartilhado, para que cada release sirva exatamente o código a partir do qual foi gerada.
- Rolling updates não exigem nada de especial. Pods novos trazem o próprio cache; pods antigos mantêm o deles.
- Quando a imagem não pode conter o cache, rode
cache:warmup:aopem um init container que grava em um volumeemptyDirmontado no caminho de cache do container da aplicação. Isso mantém oPREBUILT_CACHE, e o pod fica pronto já com um cache completo. - Containers CLI (consumidores de fila, cron jobs) usam a mesma imagem e o mesmo cache. Ative
opcache.enable_cli=1junto com oopcache.file_cachepré-aquecido; veja Processos CLI.
Workers de longa duração
Seção intitulada “Workers de longa duração”Workers de longa duração (RoadRunner, o modo worker do FrankenPHP, Swoole, ReactPHP) fazem o boot do kernel uma vez por worker. Os call contexts permanecem inicializados de uma requisição para a outra.
Escrevendo behaviors rápidos
Seção intitulada “Escrevendo behaviors rápidos”- Mire com precisão. Só os membros que correspondem à regra são interceptados e só as classes que correspondem são compiladas, então uma regra precisa é uma regra rápida.
execution(public App\Service\*->*(*))também corresponde a construtores. Acrescente&& !execution(**->__construct(*))quando não precisar deles. - Prefira regras de método a
initialization(...). Enquanto houver uma regrainitializationregistrada, cadanewnos arquivos gerados passa pelo transformer. Uma classe sem behaviors de inicialização (e com construtor público) ainda é criada por umnewnativo, que custa cerca de 130 ns a mais que umnewsimples. Uma classe com behaviors de inicialização passa pelo call context completo. - Registre as behavior classes de forma lazy com
addLazyService(). A behavior class e suas dependências são criadas na primeira chamada de um behavior, não a cada requisição. - Mantenha os behaviors baratos.
getMethod()egetField()criam um objeto de reflection no primeiro uso em cada call context. Extraia dele atributos ou nomes uma vez e guarde-os na behavior class, indexados porclass::method. - Formate call contexts de forma lazy.
(string) $invocationmonta uma string a cada chamada. Use-o só para mensagens que de fato são gravadas. - Includes nativos.
Features::INTERCEPT_INCLUDESfazinclude/requirenos arquivos gerados passarem pelo compilador, para código legado que não é carregado pelo Composer. Com ele, em produção, umincludede um arquivo conhecido pelo cache é servido pelo seu caminho original ou pelo caminho em cache, sem o stream filter (~250 µs → ~11 µs por include).
Uma behavior class registrada de forma lazy:
use Go\Core\AspectContainer;use Go\Core\AspectKernel;use Psr\Log\LoggerInterface;
class ApplicationAspectKernel extends AspectKernel{ 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)), ); }}Como escrever behaviors e matching rules está em Behaviors e matching rules.
Solução de problemas
Seção intitulada “Solução de problemas”Aquecimento e cache pré-gerado
Seção intitulada “Aquecimento e cache pré-gerado”| Mensagem ou sintoma | O que significa e o que fazer |
|---|---|
cache:warmup:aop grava erros no stderr e sai com código diferente de zero |
Um arquivo não pode ser compilado. O deploy ou o docker build para, de modo que um cache incompleto nunca seja publicado. Corrija o arquivo e rode o aquecimento de novo. |
WeavingException: ... is missing from the prebuilt AOP cache in ... |
Com PREBUILT_CACHE, uma classe ou um arquivo incluído abaixo dos include paths não tem registro no cache, ou o seu arquivo em cache sumiu. Gere o cache de novo com cache:warmup:aop. |
cache:warmup:opcache imprime um comando em vez de pré-aquecer o cache |
O processo não foi iniciado com -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR, ou --file-cache aponta para outro diretório. Rode o comando impresso. |
Erros de preloading
Seção intitulada “Erros de preloading”O PHP reporta problemas de preloading uma única vez, quando o master do PHP-FPM (ou o php -S) inicia, no seu log de erros.
| Mensagem | O que significa e o que fazer |
|---|---|
Fatal Error "opcache.preload" requires "opcache.preload_user" when running under uid 0 |
O master roda como root. Defina opcache.preload_user como o usuário com que os workers rodam (www-data). |
Failed opening required '.../_preload.php' |
O script não existe: o cache foi gerado sem --preload, ou opcache.preload aponta para outro diretório de cache. Gere de novo com cache:warmup:aop --preload. |
Go! AOP preload: <class> is left to the autoloader: ... |
O script não conseguiu carregar uma classe do cache, quase sempre porque uma dependência opcional não está instalada (uma imagem --no-dev). Inofensivo: a classe não é pré-carregada, e uma requisição que precisar dela a carrega pelo autoloader como de costume. |
Can't preload unlinked class <class>: Unknown parent/trait/interface <name> in <file> |
O OPcache não conseguiu linkar uma classe de um arquivo que o preload incluiu, pelo mesmo motivo. A mensagem aparece junto com a da linha acima quando se trata de uma classe do cache. Inofensivo: a classe simplesmente não é pré-carregada. |
Can't preload unlinked class class@anonymous: Unknown trait ... em um arquivo auxiliar do vendor |
Uma classe anônima de um autoload files do Composer, por exemplo o Illuminate/Reflection/helpers.php do Laravel. O script do cache deixa esses arquivos de fora; o aviso vem de outro script que faz require de vendor/autoload.php antes dele. Carregue o script do cache primeiro: o Composer então devolve o seu loader sem incluir os arquivos de novo. |
Reproduzindo os benchmarks
Seção intitulada “Reproduzindo os benchmarks”A aplicação, os scripts de benchmark e a imagem Docker estão em goaop/shop-demo. Um único script reproduz todas as tabelas desta página:
bash bench/run-all.shComo os números foram medidos
Seção intitulada “Como os números foram medidos”- Aplicação: ~45 classes escritas à mão (domínio, repositórios, serviços, controllers, infraestrutura em memória), 40 módulos gerados (service e repository compilados; DTO, validator e event não compilados) e 120 classes de biblioteca fora dos include paths.
- Behavior classes: logging (
#[Before]em um atributo), cache e transações (#[Around]em atributos), monitoramento (#[Around]em repositórios,#[AfterThrowing]em serviços), auditoria de estoque (#[Around]em uma propriedade), segurança (#[Before]em serviços de módulo). - Baseline: o mesmo código sem o kernel. Seus behaviors não rodam.
- Runtime: PHP 8.5.12 NTS, 4 CPUs, OPcache com
opcache.jit=disableeopcache.file_update_protection=0. - Requisições web: o servidor web embutido (
php -S, um worker, memória compartilhada do OPcache mantida entre as requisições). Morna é a primeira requisição de um servidor recém-iniciado (7 amostras); quente é a mediana de 350 requisições. Os tempos são medidos dentro do script comhrtime(). - Perfis: execuções do Xdebug 3.5 com
xdebug.mode=profileem todos os modos e estados, usadas para as contagens de chamadas e a distribuição do tempo. Os tempos vêm de execuções sem Xdebug.
São as proporções entre os modos que se mantêm em outras máquinas.
© 2026 Alexander Lisachenko
