Como depurar um erro 500 ou uma página em branco no PrestaShop

Poucas coisas assustam mais do que abrir a sua loja e ver uma página em branco ou um seco «500 Internal Server Error». A boa notícia: a causa está quase sempre escrita em algum lado. Esta é a ordem pela qual a procuramos.

1. O que mudou?

Antes de mexer em nada: instalou-se ou atualizou-se um módulo? Mudou a versão de PHP do alojamento? Carregou-se algum ficheiro? 80 % das falhas coincidem com uma alteração recente. Se houver uma, já tem o primeiro suspeito.

2. Ative o modo de depuração (com cuidado)

Em config/defines.inc.php:

define('_PS_MODE_DEV_', true);

Com o modo de depuração, o PrestaShop mostra o erro completo no ecrã em vez de uma página vazia. Faça-o só durante o tempo indispensável: a mensagem pode revelar caminhos do servidor a qualquer visitante. Se puder, reproduza-o numa cópia da loja em vez de em produção.

3. Leia os registos

• var/logs/: os registos do PrestaShop e do Symfony (prod-AAAA-MM-DD.log). Procure CRITICAL e ERROR.
• O registo de erros de PHP do alojamento (no cPanel costuma estar em Métricas > Erros ou num error_log na raiz).
• O registo do servidor web, se a página nem sequer chega ao PHP.

grep -E "CRITICAL|ERROR" var/logs/prod-$(date +%F).log | tail -20

4. Exclua módulos e overrides

Em Parâmetros avançados > Desempenho pode desativar temporariamente os módulos que não são do PrestaShop e os overrides. Se a loja voltar, a causa está num deles: reative-os por metades até o encontrar.

5. Limpe a cache, mas bem

Apague o conteúdo de var/cache/prod e var/cache/dev, não a pasta var/cache inteira: em algumas versões vive lá um ficheiro de parâmetros de que o PrestaShop precisa para arrancar.

6. As páginas «em branco com 200»

São as mais traiçoeiras: o servidor responde bem, mas não há conteúdo. As causas que mais vemos:

• Um módulo ou uma firewall ao nível do PHP que corta o pedido com exit.
• Uma função que não existe no PHP do servidor. Por exemplo, gerar miniaturas em AVIF quando a biblioteca GD não traz suporte para esse formato.
• Memória esgotada ao gerar uma página muito pesada.

Aqui ajuda muito executar a página a partir da linha de comandos com um auto_prepend_file que registe, no fim, os últimos ficheiros carregados: diz-lhe exatamente onde parou.

7. Quando já o encontrou

Corrija, desative o modo de depuração, limpe a cache e anote o que aconteceu. Da próxima vez que ocorrer, alguém o resolve em cinco minutos em vez de numa tarde.