Debug no WordPress sem sofrimento: como o Acorn melhora o WP_DEBUG

Se desenvolves temas ou plugins para WordPress, há uma regra simples que evita perder horas a adivinhar: no ambiente local, WP_DEBUG tem de estar ligado. O problema é que o output padrão do WordPress é… funcional, mas pouco amigável. Mostra notices e erros diretamente na página, sem grande contexto, stack trace decente ou uma apresentação que ajude mesmo a localizar a origem do problema.

Neste artigo vou explicar como o Acorn (a camada Laravel-friendly do ecossistema Roots) melhora significativamente a experiência de debugging quando WP_DEBUG está ativo — e quais são as alternativas quando não estás a usar Acorn.

O essencial do WP_DEBUG (e porque deve estar sempre ligado em desenvolvimento)

O WordPress tem um modo de debug controlado pela constante WP_DEBUG. Quando está ativo, o runtime passa a expor notices, warnings e fatal errors que muitas vezes ficam silenciosos em produção. Isto é especialmente importante no ecossistema WordPress, onde é comum encontrar código de terceiros a emitir notices — e isso pode mascarar problemas reais no teu código.

Se trabalhas com Bedrock (o boilerplate moderno da Roots que organiza o WordPress com Composer), a boa notícia é que, por defeito, o debug já vem preparado para ambientes de desenvolvimento, o que ajuda a manter consistência entre projetos e máquinas.

Porque o output padrão do WP_DEBUG não chega para projetos mais sérios

O comportamento típico do WordPress, com WP_DEBUG e WP_DEBUG_DISPLAY ligados, é despejar a mensagem do erro diretamente no HTML da página. É melhor do que nada, mas na prática tens três dores recorrentes:

Pouco contexto: muitas mensagens aparecem sem um stack trace realmente útil.
Baixa legibilidade: erros misturam-se com o markup e quebram a leitura.
Diagnóstico lento: entre includes, hooks e templates, encontrar a origem exata pode ser penoso.

Exemplo do output padrão do WP_DEBUG no WordPress, mostrando notices diretamente no ecrã — O WP_DEBUG padrão é direto, mas pouco legível e com contexto limitado. — *Forrás: Roots.io*

O que o Acorn muda quando o WP_DEBUG está ativo

O Acorn melhora o output do WP_DEBUG quando WP_DEBUG && WP_DEBUG_DISPLAY estão ligados. Na prática, ele substitui aquela experiência “raw” por um handler de exceções mais moderno, com páginas de erro bem estruturadas.

Isto é particularmente interessante em projetos onde já existe uma cultura Laravel: o Acorn permite trazer padrões e ergonomia do Laravel para dentro do WordPress (incluindo helpers e uma organização de código mais “aplicação”).

Output por defeito do Acorn: handler do Symfony

Por defeito, o Acorn utiliza o Symfony exception handler, que apresenta erros e exceções de forma muito mais legível do que o output nativo do WordPress. Ganha-se rapidamente em clareza: mensagem, localização, stack trace e um layout que não te obriga a vasculhar HTML partido.

Página de erro do Acorn usando o Symfony exception handler com stack trace e informação estruturada — Com Acorn, o output do WP_DEBUG torna-se mais informativo e fácil de ler. — *Forrás: Roots.io*

Com Ignition: uma experiência ao estilo Laravel (Acorn v3)

Se vens do Laravel, provavelmente já conheces o Ignition — a página de erro padrão do Laravel desde a versão 9. A partir do Acorn v3, com suporte a routing no estilo Laravel, o Ignition também passa a ser suportado em sites WordPress que usam Acorn. Para muitos workflows, é a melhor experiência de tratamento de erros disponível neste contexto.

Página de erro do Acorn com Ignition, semelhante ao debug do Laravel, com stack trace e detalhes da exceção — Ignition no WordPress via Acorn v3: uma experiência muito próxima do Laravel. — *Forrás: Roots.io*

Para começares a usar Ignition num projeto WordPress com Acorn, instala-o via Composer (nota: como dependência de desenvolvimento) a partir da mesma diretoria onde o Acorn está instalado:

composer require spatie/laravel-ignition --dev

composer require spatie/laravel-ignition --dev

Quando isto faz diferença a sério

Ignition brilha quando estás a iterar rapidamente em código PHP (temas, custom plugins, integração com serviços) e queres reduzir o tempo entre “rebentou” e “já sei onde é”. A legibilidade do stack trace e o contexto apresentado fazem mesmo diferença no dia a dia.

E o whoops? (especialmente relevante para Acorn v2)

Antes do Acorn v3, era comum emparelhar o Acorn com o whoops (biblioteca de error pages para PHP) para melhorar o debug em WordPress. Em projetos ainda em Acorn v2, continua a ser uma opção para ter uma experiência superior à página padrão do Symfony — embora a recomendação da Roots seja atualizar para o Acorn v3 quando possível.

Output do WP_DEBUG com Acorn e whoops, exibindo uma página de erro mais rica do que a padrão do WordPress — whoops é uma alternativa válida em setups mais antigos, como Acorn v2. — *Forrás: Roots.io*

Se não usas Acorn: alternativas no ecossistema WordPress

Nem todos os projetos vão estar em Bedrock/Acorn, e está tudo bem. Ainda assim, dá para melhorar bastante o teu ambiente local com plugins de debugging focados no WordPress. Dois clássicos:

Query Monitor — para muitos, ferramenta obrigatória em qualquer WordPress local; ajuda a inspecionar queries, hooks, timings, erros PHP e muito mais.
Debug Bar — adiciona uma barra de debug com informação útil para diagnóstico durante o desenvolvimento.

Resumo prático

Mantém WP_DEBUG ligado em desenvolvimento para apanhar notices e erros cedo.
O output nativo do WordPress é limitado e pouco legível em projetos maiores.
Com Acorn, ganhas um handler moderno (Symfony) e, no Acorn v3, podes usar Ignition para uma experiência ainda melhor.
Se não usas Acorn, Query Monitor e Debug Bar continuam a ser escolhas sólidas para depurar com mais contexto.