Lendo e entendendo os logs de erros do WordPress, parte 1

À medida que continuamos analisando o que significa ser um desenvolvedor independente do WordPress, as ferramentas necessárias e as várias estratégias que podem melhorar nosso conjunto de habilidades, venho falando sobre as várias constantes, plugins e ferramentas para nos ajudar.

Se você está apenas tropeçando neste post, recomendo verificar meu guia para ferramentas nativas de depuração do WordPress, bem como o restante dos posts da série até agora.

Afinal, acho importante que todos trabalhemos na mesma base – ou algo intimamente relacionado – ao analisar essas informações.

Em última análise, usar uma ferramenta como o Xdebug é indispensável, mas temos que trabalhar para isso (para quem está curioso, escrevi um breve guia sobre isso há pouco mais de um ano).

Por enquanto, porém, vamos começar com o básico. No post anterior, saí com a seguinte declaração:

Na próxima postagem, começaremos a analisar o que é necessário para examinar o log de erros gerado pelo WordPress e como entender as informações que vemos.

E é isso que eu quero ver hoje porque, se nada mais, lhe dará algo prático com o qual trabalhar.

Entendendo os logs de erros do WordPress, parte 1

Antes de ir muito longe nisso, quero abordar uma questão que foi levantada por um membro do site.

Ou seja, me perguntaram:

Quando vamos olhar para os princípios orientados a objetos?

Embora eu tenha abordado um pouco sobre isso em uma série anterior, é algo que estou trabalhando para abordar mais detalhadamente mais adiante nesta série.

Com isso dito, porém, vamos começar a examinar os logs de erros.

Configurando suas constantes

Se você não configurou as constantes em seu arquivo wp-config.php, recomendo fazê-lo agora, pois isso lhe dará o maior nível de granularidade ao examinar quaisquer problemas que possam surgir.

Se você não entendeu, não deixe de ler este post (e se tiver, certifique-se de que as seguintes constantes estejam definidas em seu arquivo de configuração):

<?php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
@ini_set( 'display_errors', 1 );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

Uma vez que estejam no lugar, você tem tudo o que precisa para não apenas ver as informações na tela, mas também no log de depuração que o WordPress gerará.

Onde está o registro?

Dependendo da natureza do seu ambiente, isso pode variar; no entanto, na maioria dos casos, você encontrará debug.log no diretório wp-content acima dos diretórios plugins, themes e uploads.

Como você pode ver na visualização da captura de tela acima, meu arquivo de depuração tem muito conteúdo. Veremos isso com mais profundidade na próxima seção, bem como como entendê-lo. Enquanto isso, verifique se este arquivo existe. Se existir, sinta-se à vontade para ir em frente e examinar o conteúdo do arquivo. Você pode ou não entender muito do que está acontecendo, mas o conteúdo do arquivo significa que algo em um tema ou plugin está acionando vários avisos, avisos e erros do PHP que o WordPress está capturando e despejando no arquivo de log.

O que é o arquivo de log ainda significa?

Isso não significa necessariamente que algo está quebrado, mas indica que algo não está funcionando como deveria, não está sendo capturado e tratado adequadamente no nível programático ou está simplesmente fazendo algo que não deveria estar fazendo.

Não precisa ser assim (mas pode!).

Como desenvolvedores, devemos nos esforçar para garantir que nosso código não gere nada que possa ser gravado no log de erros.

Uma coisa é fazer isso no desenvolvimento, pois podemos obter informações sobre o que estamos fazendo e como o WordPress está se saindo. É outra coisa, porém, para algo que lançamos no nível de produção para gerar essas coisas.

Lendo o log de erros

Obviamente, há mais na leitura do log de erros do que apenas abri-lo. Para muitos, a impressão inicial é que pode ser um monte de jargão. Eu entendo isso também. Mas quando você entende o que está mostrando, é muito mais fácil de entender.

Então, vamos dar uma olhada em um exemplo muito simples. Este também não é um exemplo inventado. Na verdade, este é um que veio de um plugin no qual eu estava trabalhando. O log de erros contém as seguintes informações :

[05-Jul-2018 19:43:53 UTC] PHP Fatal error:  Uncaught Error: Class 'EasyEmailExportAdminEmailExportSubmenu' not found in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php:37
#8 /U in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 37
[05-Jul-2018 19:44:03 UTC] PHP Warning:  include_once(./src/Admin/EmailExportSubmenu.php): failed to open stream: No such file or directory in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 25
[05-Jul-2018 19:44:03 UTC] PHP Warning:  include_once(): Failed opening './src/Admin/EmailExportSubmenu.php' for inclusion (include_path='.:/usr/local/Cellar/php/7.2.5/share/php/pear') in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 25

Observe que, na essência acima, existem três linhas. O melhor curso de ação ao ler os logs de erros é começar de baixo e ir subindo. Isso ocorre porque as coisas, ao serem executadas em execução, operam em uma pilha.

Uma breve digressão sobre as pilhas

Não vou entrar na definição do termo em ciência da computação, mas o código é executado e funciona de tal forma que as funções ocorrem e, literalmente, na memória de um computador, empilham-se umas sobre as outras.

Assim, a coisa mais recente a ser executada sempre estará no topo, onde a raiz de onde começa está na parte inferior. Como estamos escrevendo código em um aplicativo pré-existente, isso é o WordPress; então nosso código provavelmente estará sempre no topo.

Entendendo os logs de erros do WordPress: não é esse tipo de pilha

A ideia é que o código comece a ser executado no WordPress e siga até o trabalho que estamos fazendo. Quando há um aviso, um aviso ou um erro, geralmente será algo em nosso código (embora o WordPress não seja isento, geralmente é esse o caso).

Então, quando você lê o log de erros, você está, em essência, lendo o que é chamado de rastreamento de pilha. A Wikipedia, conforme link, tem uma definição bastante aprofundada sobre o assunto, mas talvez a parte mais relevante para este post seja a seguinte:

Os programadores geralmente usam o rastreamento de pilha durante a [depuração] interativa e post-mortem (https://en.wikipedia.org/wiki/Debugging). Os usuários finais podem ver um rastreamento de pilha exibido como parte de uma mensagem de erro, que o usuário pode relatar a um programador.

Isso combina com o que eu descrevi acima, certo? Mas chega de falar sobre o que é um rastreamento de pilha (se tornará mais claro à medida que nos aprofundarmos na depuração), vamos voltar a ler o arquivo de log como está atualmente.

Voltar para Ler o Log

Incluindo arquivos

Primeiro, vamos olhar para a linha de fundo na essência acima. Ele contém o seguinte:

[05-Jul-2018 19:44:03 UTC] PHP Warning: include_once(): Failed opening './src/Admin/EmailExportSubmenu.php' for inclusion (include_path='.:/usr/local/Cellar/php/7.2.5/share/php/pear') in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 25

Isso está me dizendo que na linha 25 do meu arquivo, easy-email-export.php, ele falhou ao abrir um arquivo para inclusão. Isso significa que eu tenho uma instrução include_once no código que está referenciando ./src/Admin/EmailExportSubmenu.php que ele não pode encontrar.

Portanto, o melhor curso de ação seria encontrar a linha 25 e determinar por que ela não está localizando o arquivo. Talvez isso esteja descartando o caminho completo para onde está olhando. Chegaremos a isso momentaneamente quando falarmos sobre gravar no log de erros.

Entendendo os Erros

Na próxima linha (ou seja, a linha acima da que acabamos de ver) contém o seguinte:

[05-Jul-2018 19:44:03 UTC] PHP Warning: include_once(./src/Admin/EmailExportSubmenu.php): failed to open stream: No such file or directory in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 25

Essa linha em particular difere apenas um pouco, mas fornece informações adicionais e está contida na cláusula que diz “Nenhum arquivo ou diretório". Isso é perspicaz porque está literalmente nos dizendo que o arquivo não existe.

Pelo menos, não existe onde está olhando. Então as duas possibilidades são:

1. não criamos o arquivo ao qual somos referências,
2. estamos referenciando a localização do arquivo no lugar errado

Assim, a primeira coisa que precisaríamos verificar é se o arquivo existe no local que estamos tentando incluir. Se isso não acontecer, então devemos criar o arquivo.

Se o arquivo existir, sabemos que o plug-in está tentando carregá-lo do caminho errado. Portanto, podemos precisar examinar nosso autoloader, nosso caminho de inclusão ou como os arquivos estão sendo recuperados. Porque, provavelmente, se o arquivo existe, ele está tentando ser carregado de um lugar que não reside.

Um erro não detectado

Na linha final do código, você verá algo assim:

[05-Jul-2018 19:43:53 UTC] PHP Fatal error: Uncaught Error: Class 'EasyEmailExportAdminEmailExportSubmenu' not found in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php:37
#8 /U in /Users/tommcfarlin/Dropbox/Projects/trunk/wp-content/plugins/easy-email-export/easy-email-export.php on line 37

Este é um bom exemplo, primeiro, porque declara explicitamente que este é um erro não detectado. Isso significa que qualquer que seja a funcionalidade, algo está gerando um erro e não está sendo capturado.

• isso pode ser uma exceção,
• isso pode ser um problema ao tentar chamar uma função que não existe,
• isso pode estar operando em uma variável que não está definida,
• e assim por diante.

Em última análise, há uma infinidade de problemas que podem estar presentes. A boa notícia, neste exemplo, é que é praticamente igual ao que está acima: Um arquivo não foi encontrado.

Exceto que, em vez de lançar um aviso, o PHP nos segue explicitamente, este é um erro fatal e o programa não pode continuar a execução até que essa linha de código seja resolvida. Antes de descartar isso como algo que é o mesmo que a seção anterior (porque, de certa forma, é), precisamos reconhecer que isso é explicitamente declarado como um erro fatal, enquanto no exemplo anterior foi tratado como um erro aviso.

Existem diferentes maneiras de conceituar isso, mas a maneira como eu geralmente penso sobre isso é:

• Um aviso me diz que algo está errado no código, mas não é ruim o suficiente para justificar a interrupção da execução.
• Um aviso é um pouco mais sério porque significa que algo corre o risco de não funcionar.
• Um erro direto diz "isso não funciona e o programa não pode continuar".

Agora sabemos que o problema é de parar o show, por assim dizer, e sabemos qual é o problema. Simplificando, um arquivo necessário para o programa concluir sua execução não é encontrado e, portanto, o programa para de funcionar.

Isso é certamente um erro fatal.

Qual é a solução?

O que forneço como solução para o meu problema não será prescritivo sobre o que funcionará para você. Para mim, era uma questão de uma linha na minha configuração do Composer de modo que o autoloader do Composer não pudesse localizar o arquivo no local apropriado (mas isso tem mais a ver com organização de arquivos, namespace e assim por diante).

Para você, pode ser algo diferente.

• talvez esteja procurando por um arquivo no diretório errado,
• talvez o arquivo tenha um nome diferente do que está especificado no código,
• ou talvez seja outra coisa.

Seja qual for o caso, o ponto é que é uma questão de percorrer o arquivo de log de baixo para cima para diagnosticar o problema e rastrear o que PHP, WordPress e seu trabalho estão fazendo e, em seguida, diagnosticá-lo a partir daí.

Gravando no log de erros

No próximo post, vamos tirar um momento para ver como podemos gravar no log de erros. Às vezes, ler o arquivo é bom e simplesmente ir e voltar entre o que estamos vendo e resolver os problemas é bom.

Mas e o caso de quando queremos despejar algo para obter informações sobre o que o WordPress ou PHP está vendo? Isso também é útil.

Então, na próxima parte desta série sobre como entender os logs de erros do WordPress, faremos exatamente isso.

O que há depois disso?

Em seguida, veremos como usar alguns dos plug-ins descritos anteriormente para testar o código e também criar o perfil do nosso código para garantir que fizemos tudo o que podemos para garantir que estamos produzindo um nível de qualidade.

Isso não significa que terminamos completamente o processo de depuração, mas definitivamente estamos um passo mais perto e estamos posicionados para escrever código com um grau de qualidade que não resulte em um arquivo representando vários problemas sutis fomos muito descuidados para consertar (quanto mais entender).