Debugando no WordPress do jeito certo. Como detectar erros antes que aconteçam.

Debugar código PHP é parte do cotidiano de desenvolvedores. Esteja você criando um tema, um plugin ou dando suporte e manutenção à uma loja/site existente.

Conseguir enxergar as mensagens de erro, alertas e avisos ao invés de uma tela branca é essencial para entender o que está errado, e assim descobrir o que fazer em seguida.

Neste artigo você encontrará algumas ferramentas de debug do WordPress, e como ser mais eficiente durante o desenvolvimento de plugins e temas.

Lembre-se de sempre ativar mensagens de erros e alertas antes de iniciar o desenvolvimento de temas e plugins.

Isso evitará erros desagradáveis, e possíveis “telas brancas” em produção ou em futuras atualizações.

wp-config.php para desenvolvedores

O arquivo wp-config.php, localizado na raiz do seu WP contém diversas configurações, incluindo configs de banco de dados e muitas outras.

Localize as constantes abaixo ou adicione aquelas que não estiverem definidas em seu arquivo wp-config.php, conforme mostrado abaixo. Isso fará com que todos os erros e avisos sejam exibidos.

// Habilita o modo WP_DEBUG
define( 'WP_DEBUG', true );

// Habilita logs no arquivo /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Mostra erros e warnings do WP e PHP
define( 'WP_DEBUG_DISPLAY', true );
@ini_set( 'error_reporting', E_ALL);  // adicione ' & ~E_NOTICE' (sem aspas) depois do E_ALL para evitar avisos mais simples, como de variáveis não declaradas
@ini_set( 'display_errors', 1);
@ini_set( 'display_startup_errors', 1 );

// Usa arquivos não minificados de JS e CSS (útil se você pretende modificá-los)
define( 'SCRIPT_DEBUG', true );

WP-DEBUG

Essa constante PHP é usada pra ativar o modo debug por todo WordPress. Note que não é recomendado usá-lo em ambiente de produção (assim como as demais configs acima).

Erros e avisos do PHP

Ao usar a constante WP_DEBUG com valor true, erros, avisos e advertências do PHP serão exibidos na tela. Por padrão, o PHP esconderia erros e avisos, o que dificulta nosso trabalho de entender o que está acontecendo.

WP_DEBUG_LOG

Esse amiguinho do WP_DEBUG faz com que todos os erros sejam salvos no arquivo debug.log. Isso pode ser útil em ambientes de produção, onde não desejamos exibir erros para o cliente final, mas desejamos analisá-los depois.

Além disso, podemos gravar erros manualmente neste arquivo ao chamar o método error_log(), nativo do PHP.

Quando setado como true, ele salvará os erros em um arquivo debug.log no diretório wp-content. Mas também podemos especificar outro caminho, como mostrado abaixo:

define( 'WP_DEBUG_LOG', true );
-ou-
define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

Note: Para o WP_DEBUG_LOG funcionar, é preciso que o WP_DEBUG esteja configurado como true.

WP_DEBUG_DISPLAY

Outro amiguinho do WP_DEBUG, faz com que mensagens de erro sejam ou não exibidas dentro de páginas HTML. Por padrão, este valor é true. Configurar como false fará os erros serem escondidos.

Note: Para o WP_DEBUG_DISPLAY funcionar, é preciso que o WP_DEBUG esteja configurado como true.

SCRIPT_DEBUG

Alguns arquivos CSS e JS possuem versões minificadas e comprimidas. Essas versões são geralmente ilegíveis, pois não possuem quebra de linhas, espaços, comentários, e suas variáveis são renomeadas com menos caracteres.

Ao definir a constante SCRIPT_DEBUG, os arquivos originais serão carregados. Além do core do WordPress, muitos módulos também fazem uso desta constante para definir que arquivo será carregado.

Salvando e exibindo queries do WordPress

Uma outra constante que pode ser definida no seu wp-config.php é a SAVEQUERIES.

define( 'SAVEQUERIES', true );

Ao fazer isso, todas as queries executadas serão salvas em um array que pode ser exibido posteriormente. Ele também guardará o tempo que o SQL levou para ser executado e que método o chamou.

O array é salvo na propriedade global $wpdb->queries.

Plugins de Debug

Existem centenas de plugins para desenvolvimento WordPress, e certamente falarei deles em cursos e outros conteúdos por aqui.

Abaixo recomendarei 3 que estão na documentação oficial do WordPress, e também onde me inspirei para criar este artigo.

• Query Monitor – Mostra visualmente as informações de queries, tempo de execução e suas origens.
• Debug Bar – Barra de debug que mostra informações de queries, actions, hooks, caches, filtros, e outras coisas úteis
• Log Deprecated Notices – Um quase substituto ao WP_DEBUG, mostrando os erros e warnings num grid bonitinho, no admin, ao invés de exibir na tela.

Uma outra ferramenta útil para desenvolvedores é o gerador de wp-config.php. Este site permite você gerar arquivos wp-config.php com configurações básicas e avançadas, inclusive modificando configurações do PHP e do wp_options.

• Sobre
• Últimos Posts

Ricardo Martins

É desenvolvedor web há 16 anos e um dos primeiros certificados pela Magento no Brasil. Instrutor de mais de 11 cursos Magento (os principais no magenteiro.com/cursos) com mais de 14 mil alunos de 105 países, é também criador do módulo PagSeguro Transparente, usado em mais de 12 mil lojas.

Últimos posts por Ricardo Martins (exibir todos)

• Guest checkout bloqueado na API REST do Magento 2? Confira isso. - 7 de julho de 2026
• Você precisa testar esta plataforma de e-commerce - 9 de fevereiro de 2026
• A hora de montar o seu OnlyFans chegou! Veja 8 ideias pra começar o seu. - 4 de dezembro de 2024