Como Resolver o Erro ‘Composer detected issues in your platform’ no WordPress

Ao gerenciar temas, plugins avançados ou estruturas modernas de WordPress (como Bedrock), deparar-se com uma tela em branco acompanhada da mensagem Composer detected issues in your platform: Your Composer dependencies require a PHP version... pode paralisar uma operação. O erro interrompe a execução da aplicação antes mesmo do bootstrap do WordPress, impedindo o carregamento de qualquer página.

Esse bloqueio não decorre de uma falha de código no núcleo do CMS, mas sim de uma incompatibilidade entre os requisitos declarados no gerenciador de pacotes e o ambiente de execução real.

Por que o Composer bloqueia a execução?

A partir da versão 2, o Composer introduziu por padrão a verificação de plataforma (platform_check). Durante o processo de compilação ou instalação das dependências (composer install ou composer update), o Composer gera um arquivo de verificação dentro de vendor/composer/platform_check.php.

Esse arquivo valida estritamente:

1. A versão do PHP executada no momento da requisição HTTP (via PHP-FPM, Apache mod_php ou Nginx FastCGI).
2. A presença de extensões PHP obrigatórias exigidas pelas bibliotecas instaladas (como ext-mbstring, ext-curl ou ext-json).

Se o ambiente local do desenvolvedor estiver rodando PHP 8.2 e o servidor de produção estiver configurado com PHP 8.0, o Composer abortará a execução com exit(255) para prevenir falhas silenciosas de sintaxe ou métodos inexistentes.

Boas Práticas e Arquitetura de Dependências

A abordagem correta para prevenir esse problema envolve governança e paridade de ambientes, evitando ajustes paliativos que possam introduzir instabilidades.

1. Fixar a Versão da Plataforma no composer.json

Em sistemas que desenvolvo, a definição da plataforma alvo é mantida de forma explícita no arquivo de configuração do projeto. Isso impede que atualizações locais com uma versão superior do PHP gerem travas incompatíveis com a produção.

No seu composer.json, adicione a seção de configuração:

{
“config”: {
“platform”: {
“php”: “8.1.0”
}
}
}

Essa diretiva força o Composer a emular a versão estipulada durante a resolução dos pacotes, mesmo que o ambiente CLI local possua outra versão instalada.

2. Atenção à Divergência entre CLI e Web Server

Um erro recorrente é executar php -v no terminal SSH do servidor e constatar a versão correta, enquanto o site continua apresentando a falha. Lembre-se: a versão do PHP no terminal (CLI) frequentemente difere do socket utilizado pelo servidor web (Web SAPI/PHP-FPM).

Para validar a versão real que atende a requisição HTTP, crie temporariamente um arquivo de diagnóstico ou consulte as configurações do seu virtual host.

Passo a Passo para Solucionar o Erro

Passo 1: Identificar a Versão PHP do Servidor

Descubra a versão exata do PHP em execução no ambiente de produção. Caso o servidor suporte múltiplos PHP-FPM, certifique-se de que o pool correto esteja vinculado ao domínio.

Passo 2: Atualizar ou Sincronizar o PHP do Servidor

Se a sua infraestrutura permitir, a solução mais sustentável é atualizar o PHP do servidor web para a versão demandada pelas dependências modernas (atualmente PHP 8.1 ou 8.2 são recomendados para WordPress).

Passo 3: Regenerar o Autoloader com os Parâmetros Corretos

Se não for possível atualizar o PHP do servidor de imediato, alinhe o composer.json localmente à versão suportada e regere o arquivo de dependências:

bash
composer update –with-all-dependencies
composer dump-autoload

Envie os arquivos composer.lock e o diretório vendor/ (ou execute a instalação via pipeline de CI/CD) para o ambiente de produção.

Passo 4: Desativação Temporária do Platform Check (Uso Excepcional)

Se você tem certeza de que o código é retrocompatível e precisa restaurar o sistema imediatamente sem alterar dependências, é possível desativar a verificação no build:

bash
composer dump-autoload –no-platform-check

Nota: Esta prática deve ser encarada como medida emergencial, pois ignora proteções arquiteturais nativas do Composer.

Considerações Finais

A resolução de erros de plataforma no WordPress exige rigor técnico no gerenciamento de dependências e sincronia entre ambientes de desenvolvimento e produção. Implementar pipelines de deploy automatizados e padrões rígidos de configuração evita que atualizações de pacotes quebrem sites em produção.

Se a sua empresa precisa de suporte especializado para estruturar ambientes WordPress corporativos, pipelines de deploy ou resolução de inconsistências críticas em servidores, entre em contato para uma consultoria técnica.