Como ativar OPcache no PHP 8.3: do zero ao funcionando

16 min de leitura  ·  Guia técnico

OPcache no PHP 8.3 é um acelerador de bytecode nativo que armazena o código PHP pré-compilado na memória compartilhada, eliminando a necessidade de recompilar os arquivos a cada requisição. Para ativar o OPcache do zero até funcionar, siga estes passos:

1. Verifique se o pacote OPcache está instalado no sistema
2. Edite o arquivo php.ini ou crie um arquivo de configuração dedicado
3. Adicione e ajuste as diretivas essenciais do OPcache
4. Reinicie o PHP-FPM ou o servidor web
5. Confirme que o OPcache está ativo via terminal ou phpinfo()

Pré-requisitos para ativar o OPcache no PHP 8.3

• Acesso root ou sudo ao servidor (VPS ou dedicado)
• PHP 8.3 instalado — verifique com php -v
• Distribuição compatível: Rocky Linux 9, AlmaLinux 9, Ubuntu 24.04 LTS ou Debian 12
• PHP-FPM ou Apache com mod_php configurado e em execução
• Editor de texto disponível: nano, vim ou similar
• Conhecimento básico de terminal Linux

Como ativar o OPcache no PHP 8.3: verificação inicial do pacote

Antes de editar qualquer arquivo de configuração, confirme se a extensão OPcache já está presente no sistema. Em distribuições baseadas em RHEL como Rocky Linux 9 e AlmaLinux 9, o OPcache é instalado automaticamente com o PHP, mas pode estar desabilitado. Execute o comando abaixo para verificar:

php -m | grep -i opcache

Zend OPcache

Se o retorno for vazio, o módulo não está carregado — mas provavelmente está instalado. Verifique o arquivo de configuração existente:

# Rocky Linux 9 / AlmaLinux 9
ls /etc/php.d/ | grep opcache

# Ubuntu 24.04 / Debian 12
ls /etc/php/8.3/mods-available/ | grep opcache

# Saída esperada em Rocky/AlmaLinux:
10-opcache.ini

# Saída esperada em Ubuntu/Debian:
opcache.ini

Se o arquivo existir mas o módulo não aparecer no php -m, o arquivo pode estar com a extensão desabilitada ou o PHP-FPM precisa ser reiniciado. Caso o pacote realmente não esteja instalado, instale-o conforme sua distribuição:

# Rocky Linux 9 / AlmaLinux 9
dnf install php8.3-opcache -y

# Ubuntu 24.04 / Debian 12
apt install php8.3-opcache -y

# Saída esperada (Ubuntu):
Setting up php8.3-opcache (8.3.x-...) ...

Configurando as diretivas do OPcache no php.ini

O acelerador de bytecode PHP funciona melhor quando suas diretivas são ajustadas para o perfil da aplicação. Localize o arquivo php.ini correto para o contexto em uso — CLI e FPM usam arquivos diferentes:

# Encontrar o php.ini do PHP-FPM
php-fpm8.3 -i 2>/dev/null | grep "Loaded Configuration File"

# Alternativa universal
php --ini | grep "Loaded Configuration File"

Loaded Configuration File => /etc/php/8.3/fpm/php.ini

A prática recomendada é criar um arquivo dedicado em vez de editar o php.ini principal. Isso facilita atualizações futuras do PHP sem perder as configurações:

# Ubuntu 24.04 / Debian 12
nano /etc/php/8.3/fpm/conf.d/99-opcache-custom.ini

# Rocky Linux 9 / AlmaLinux 9
nano /etc/php.d/99-opcache-custom.ini

Adicione o bloco de configuração abaixo. Cada diretiva está comentada para facilitar o entendimento:

[opcache]
; Habilita o OPcache
opcache.enable=1

; Habilita OPcache para CLI (útil para scripts de linha de comando)
opcache.enable_cli=0

; Memória alocada para o cache de bytecode (em MB)
opcache.memory_consumption=128

; Memória para strings internadas (nomes de variáveis, chaves de array)
opcache.interned_strings_buffer=16

; Número máximo de arquivos PHP que podem ser cacheados
opcache.max_accelerated_files=10000

; Intervalo em segundos para verificar mudanças nos arquivos (0 = nunca)
opcache.revalidate_freq=60

; Salva comentários de docblock no cache (necessário para frameworks como Laravel)
opcache.save_comments=1

; Valida permissões de arquivo antes de usar o cache
opcache.validate_permission=0

; Habilita otimizações agressivas de bytecode (PHP 8.x)
opcache.jit_buffer_size=64m
opcache.jit=tracing

Atenção: a diretiva opcache.jit=tracing ativa o compilador JIT do PHP 8.3, que pode aumentar significativamente a performance de código CPU-intensivo. Para aplicações web comuns como WordPress, o ganho do JIT é menor do que o do cache de bytecode em si. Teste antes de aplicar em produção.

Para aplicações de maior porte como Laravel em produção, ajuste opcache.memory_consumption para 256 e opcache.max_accelerated_files para 20000. Veja mais sobre otimização de servidores Linux em Dicas de Otimização de Servidores Linux.

Reiniciando o PHP-FPM e validando a ativação do OPcache

Após salvar o arquivo de configuração, o serviço PHP-FPM precisa ser reiniciado para carregar as novas diretivas. O comando varia conforme a distribuição:

# Ubuntu 24.04 / Debian 12
systemctl restart php8.3-fpm
systemctl status php8.3-fpm

# Rocky Linux 9 / AlmaLinux 9
systemctl restart php-fpm
systemctl status php-fpm

# Apache com mod_php (Ubuntu/Debian)
systemctl restart apache2

# Apache com mod_php (Rocky/AlmaLinux)
systemctl restart httpd

# Saída esperada do status:
● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded (/lib/systemd/system/php8.3-fpm.service; enabled)
     Active: active (running) since ...

Agora confirme que o OPcache está ativo via terminal:

php -r "var_dump(opcache_get_status());"

array(7) {
  ["opcache_enabled"]=>
  bool(true)
  ["cache_full"]=>
  bool(false)
  ["restart_pending"]=>
  bool(false)
  ["restart_in_progress"]=>
  bool(false)
  ["memory_usage"]=>
  array(4) {
    ["used_memory"]=>
    int(...)
    ["free_memory"]=>
    int(...)
    ...
  }
  ...
}

Se opcache_enabled retornar bool(true), o OPcache está funcionando corretamente. Para verificar via web, crie um arquivo temporário de diagnóstico:

echo "<?php phpinfo();" > /var/www/html/info.php

Acesse http://seu-dominio.com/info.php no navegador e procure pela seção Zend OPcache. Após confirmar, remova o arquivo imediatamente por segurança:

rm /var/www/html/info.php

Ajustando o OPcache para WordPress e Laravel no PHP 8.3

A configuração ideal do cache de bytecode PHP varia conforme o tipo de aplicação. WordPress e Laravel têm perfis de uso distintos que exigem ajustes específicos nas diretivas.

Para WordPress:

• opcache.memory_consumption=128 — suficiente para a maioria das instalações com plugins moderados
• opcache.max_accelerated_files=5000 — WordPress core + plugins comuns ficam abaixo desse número
• opcache.revalidate_freq=60 — verifica mudanças a cada 60 segundos, equilibrando performance e atualização
• opcache.save_comments=1 — necessário para plugins que usam anotações em docblocks

Para Laravel:

• opcache.memory_consumption=256 — Laravel e seus pacotes Composer geram muitos arquivos PHP
• opcache.max_accelerated_files=20000 — vendor/ do Composer pode conter milhares de arquivos
• opcache.revalidate_freq=0 — em produção, desative a verificação de mudanças para máxima performance; use opcache_reset() no deploy
• opcache.validate_timestamps=0 — elimina verificações de timestamp em produção

Atenção: ao definir opcache.validate_timestamps=0, o PHP nunca verificará se os arquivos foram modificados. Qualquer atualização de código exigirá um reinício do PHP-FPM ou chamada a opcache_reset() para que as mudanças sejam refletidas.

Para monitorar o uso real do cache e decidir se precisa aumentar a memória, use:

php -r "
\$status = opcache_get_status();
\$mem = \$status['memory_usage'];
\$total = \$mem['used_memory'] + \$mem['free_memory'] + \$mem['wasted_memory'];
echo 'Uso: ' . round(\$mem['used_memory'] / 1024 / 1024, 2) . ' MB' . PHP_EOL;
echo 'Livre: ' . round(\$mem['free_memory'] / 1024 / 1024, 2) . ' MB' . PHP_EOL;
echo 'Cache full: ' . (\$status['cache_full'] ? 'SIM - aumente memory_consumption' : 'NÃO') . PHP_EOL;
"

Uso: 42.18 MB
Livre: 85.82 MB
Cache full: NÃO

Habilitando o JIT do PHP 8.3 junto com o OPcache

O compilador Just-In-Time é uma funcionalidade do PHP 8.x que complementa o cache de bytecode ao compilar partes do código diretamente para instruções de máquina. Para ativá-lo, o OPcache deve estar habilitado — o JIT não funciona de forma independente.

As diretivas relevantes para o JIT são:

; Tamanho do buffer de memória para o JIT (separado do opcache.memory_consumption)
opcache.jit_buffer_size=64m

; Modo JIT: 'tracing' é o mais agressivo e geralmente o mais rápido
; Opções: disable, on, off, tracing, function
opcache.jit=tracing

O modo tracing analisa os caminhos de execução mais frequentes e os compila para código nativo. Para aplicações web típicas (WordPress, Magento, Drupal), o ganho do JIT costuma ser modesto — entre 5% e 15% — porque o gargalo geralmente está em I/O de banco de dados e rede, não em CPU. O JIT brilha em aplicações de processamento matemático, geração de imagens ou algoritmos intensivos.

Se você estiver em um ambiente com múltiplos sites em um único servidor, considere o impacto do jit_buffer_size multiplicado pelo número de pools PHP-FPM ativos. Cada pool aloca seu próprio buffer JIT.

Para verificar se o JIT está ativo após reiniciar o PHP-FPM:

php -r "var_dump(opcache_get_status()['jit']);"

array(4) {
  ["enabled"]=>
  bool(true)
  ["on"]=>
  bool(true)
  ["kind"]=>
  int(5)
  ["opt_level"]=>
  int(4)
  ...
}

Problemas comuns e como resolver

Sintoma: opcache_get_status() retorna false no terminal

Causa: O OPcache está habilitado para FPM (requisições web) mas não para CLI. Por padrão, opcache.enable_cli=0, o que significa que o PHP executado via linha de comando não carrega o OPcache.
Solução: Se precisar do OPcache no CLI (para scripts de deploy, por exemplo), adicione opcache.enable_cli=1 ao arquivo de configuração e reinicie. Para verificar o status via web, use um arquivo phpinfo() temporário em vez do terminal.

Sintoma: alterações no código PHP não são refletidas após deploy

Causa: O OPcache está servindo a versão antiga do bytecode em cache. Isso ocorre especialmente quando opcache.validate_timestamps=0 ou opcache.revalidate_freq está configurado com valor alto.
Solução: Após cada deploy, execute systemctl restart php8.3-fpm ou chame opcache_reset() via script PHP. Em pipelines de CI/CD, adicione o reinício do PHP-FPM como etapa final do deploy. Alternativamente, use opcache_invalidate('/caminho/do/arquivo.php', true) para invalidar arquivos específicos.

Sintoma: erro "No space left on device" ou PHP-FPM não inicia após configurar JIT

Causa: O valor de opcache.jit_buffer_size excede a memória disponível no servidor, ou o limite de memória compartilhada do sistema operacional está muito baixo.
Solução: Reduza o jit_buffer_size para 32m ou desative o JIT temporariamente com opcache.jit=off. Verifique a memória disponível com free -m e o limite de memória compartilhada com cat /proc/sys/kernel/shmmax. Se necessário, aumente o limite: sysctl -w kernel.shmmax=268435456.

Sintoma: cache_full retorna true constantemente

Causa: O valor de opcache.memory_consumption está insuficiente para o número de arquivos PHP da aplicação. Isso força o OPcache a descartar entradas antigas, reduzindo a eficiência do cache.
Solução: Aumente opcache.memory_consumption gradualmente — de 128 para 256 MB, por exemplo. Monitore com o script de diagnóstico apresentado anteriormente. Também verifique opcache.max_accelerated_files: se o número de arquivos cacheados atingir esse limite, aumente o valor.

Sintoma: Warning "Cannot load Zend OPcache" no log do PHP-FPM

Causa: O arquivo .so da extensão OPcache não foi encontrado no caminho esperado, ou há conflito com outra extensão de aceleração (como APC ou XCache, que são incompatíveis).
Solução: Verifique o caminho do arquivo com find /usr -name "opcache.so" 2>/dev/null. Confirme que a linha zend_extension=opcache.so está presente no arquivo de configuração correto. Remova qualquer referência a APC, XCache ou eAccelerator dos arquivos de configuração PHP.

Perguntas frequentes sobre OPcache no PHP 8.3

O OPcache já vem instalado no PHP 8.3?

Sim, o OPcache é uma extensão nativa do PHP desde a versão 5.5 e está incluída no pacote padrão do PHP 8.3. Em distribuições como Rocky Linux 9 e Ubuntu 24.04, ele é instalado junto com o PHP, mas precisa ser habilitado manualmente no arquivo php.ini ou em um arquivo de configuração dedicado. Verifique com php -m | grep -i opcache se a extensão já está carregada.

Qual o tamanho ideal para opcache.memory_consumption no PHP 8.3?

Para aplicações de médio porte como WordPress ou Laravel, recomenda-se entre 128 MB e 256 MB. O valor ideal depende do número de arquivos PHP únicos da aplicação: execute opcache_get_status() para verificar o uso real e ajuste conforme a taxa de cache_full — se for maior que zero, aumente o valor. Comece com 128 MB e monitore por alguns dias antes de ajustar.

Como verificar se o OPcache está ativo no servidor?

Execute php -r 'var_dump(opcache_get_status());' no terminal ou crie um arquivo phpinfo() no servidor e procure pela seção Zend OPcache. Se a função opcache_get_status() retornar false ou não existir, o OPcache não está habilitado. Reinicie o PHP-FPM após qualquer alteração no php.ini para que as mudanças sejam aplicadas.

O OPcache funciona com PHP-FPM e Apache mod_php ao mesmo tempo?

O OPcache opera por processo PHP, portanto funciona tanto com PHP-FPM quanto com mod_php, mas cada pool ou instância mantém seu próprio cache em memória. Em ambientes com múltiplos pools PHP-FPM, cada pool terá seu próprio OPcache separado, o que deve ser considerado ao dimensionar o opcache.memory_consumption. Não é possível compartilhar o mesmo cache entre pools diferentes.

Preciso reiniciar o servidor para ativar o OPcache?

Não é necessário reiniciar o servidor inteiro. Basta reiniciar o serviço PHP-FPM com systemctl restart php8.3-fpm (em sistemas Debian/Ubuntu) ou systemctl restart php-fpm (em Rocky Linux/AlmaLinux). Se estiver usando Apache com mod_php, execute systemctl restart httpd ou systemctl restart apache2. O servidor web e outros serviços continuam funcionando normalmente durante o processo.

Conclusão

Ativar e configurar corretamente o OPcache no PHP 8.3 é uma das otimizações de maior impacto que você pode fazer em qualquer aplicação PHP, com custo zero e configuração em menos de 10 minutos. Veja os próximos passos recomendados:

• Monitore o uso real do cache com opcache_get_status() após 24-48 horas em produção e ajuste memory_consumption e max_accelerated_files conforme os dados reais da sua aplicação.
• Integre o reset do OPcache ao seu pipeline de deploy — adicione systemctl restart php8.3-fpm ou uma chamada a opcache_reset() como etapa final de qualquer atualização de código para evitar servir bytecode desatualizado.
• Avalie o JIT com cautela — ative opcache.jit=tracing em ambientes de staging primeiro, meça o impacto real com ferramentas como ab ou wrk, e só então aplique em produção se houver ganho mensurável para o seu tipo de aplicação.

Para uma visão mais ampla sobre como configurar seu servidor Linux para hospedagem de alta performance, consulte o guia Configurando um Servidor Linux para Hospedagem de Sites.

Leia também

• Otimizar PHP 8.3 no Debian 12: OPcache, JIT e pool FPM
• Otimizar cache Redis para aplicações PHP no Ubuntu 22.04
• Solucionar lentidão no MySQL 8.0 antes que derrube sua aplicação

Precisa de ajuda com PHP e performance no seu site?

Configurar OPcache é apenas um dos passos para um site rápido e estável. Na AviraHost, os planos de hospedagem já incluem PHP 8.3 com suporte a OPcache e ambiente otimizado para WordPress, Laravel e outros frameworks PHP — sem precisar configurar nada manualmente.

Conheça os planos de hospedagem da AviraHost