Como configurar a depuração de PHP usando Xdebug e VSCode

Tens de prestar atenção a alguns aspectos quando desenvolves aplicações Web para obteres um produto final sem problemas. Os bons programadores seguem as melhores práticas de desenvolvimento, incluindo testes, depuração, etc., enquanto criam aplicações robustas.

Este artigo discute os conceitos de depuração do PHP e as técnicas de codificação. Portanto, continua a ler para saber mais sobre a depuração do PHP.

Podes iniciar a depuração sem qualquer configuração. Mas isto só é sugerido quando precisas de te ligar a um servidor Web existente com o Xdebug configurado ou queres executar e depurar um script PHP rapidamente.

Comecemos pelo nível básico, em que tendes a escrever código PHP utilizando os comandos print_r(), var_dump() para depurar o resultado do código escrito. Temos muitas ferramentas de depuração do PHP, que permitem ao utilizador corrigir os erros durante a codificação, e algumas funções que te mostram o resultado correto ou erros/avisos em caso de falha do código. Embora esta técnica de depuração do PHP seja básica, continua a ser utilizada.

O que são logs de erros do PHP?

Os registos de erros do PHP são instrumentos muito úteis para os programadores identificarem e resolverem problemas nas suas aplicações. Os registos de erros do PHP mostram a informação total relativa a erros, avisos e advertências em tempo de execução do script, por exemplo, o tipo de erro, em que ficheiro o erro apareceu e o número real da linha onde o erro ocorreu. Estes registos permitem aos programadores identificar falhas em tempo real e implementar medidas de correção através do seu estudo.

Porque é que os registos de erros do PHP são importantes?

• Depuração: Os registos de erros ajudam-te a determinar erros de sintaxe, erros de tempo de execução e erros lógicos no teu código.
• Monitorização do desempenho: Pode identificar estrangulamentos de desempenho ou pontos de código ineficientes.
• Segurança: Os registos podem informar-te sobre potenciais vulnerabilidades ou tentativas de acesso através de meios não autorizados.
• Segurança na produção: Na produção, os registos de erros ajudam-te a localizar problemas sem revelar informações sensíveis aos utilizadores.

Configuração do registo de erros do PHP

Para ativar e configurar o registo de erros do PHP, tens de alterar as definições no teu ficheiro php.ini ou utilizar diretivas de tempo de execução como ini_set().

I. php.ini Principais diretivas:

Estas são as diretivas principais para o registo de erros:

• log_errors: Liga ou desliga o registo de erros.

log_errors = On

• error_log: Aqui é onde os erros serão registados. Usa um caminho absoluto para que seja óbvio.

error_log = /var/log/php_errors.log

• error_reporting: Especifica que tipo de erros devem ser registados. Por exemplo:

relatório_de_erros = E_ALL

• E_ALL: Regista todos os erros, avisos e notificações.
• E_ERROR | E_WARNING: Regista os erros fatais e os avisos.

II. Registo por.htaccess (por diretório):

Se o php.ini não estiver acessível ou modificável devido a problemas de acesso limitado, podes registar por diretório através do .htaccess. Podes adicionar o seguinte bloco de código no ficheiro .htaccess da tua aplicação:

php_flag log_errors On
php_value error_log /path/to/php_errors.log

III. Configuração em tempo de execução utilizando ini_set():

Também podes ativar o registo dinamicamente nos teus scripts PHP, adicionando o seguinte bloco de código:

ini_set('log_errors', 'On');
ini_set('error_log', '/path/to/php_errors.log');

Visualizando logs de erros do PHP

Os registos de erros do PHP são guardados de forma diferente, dependendo da configuração do alojamento:

1. Localizações predefinidas:

• Para servidores Linux: /var/log/php_errors.log ou /var/log/syslog
• Para servidores Windows: Visualizador de eventos (no caso de error_log estar configurado como syslog)

b. Instruções específicas para a Cloudways:

Para os servidores geridos pela Cloudways, podes seguir facilmente os passos para ver os teus registos sem qualquer esforço extra.

• Faz login no painel de controle da Cloudways.
• Acede a Gestão de servidores > Monitorização > Registos.
• Vai à secção “Application Logs” ou “Server Logs” para verificar os erros de PHP.

Leitura do registo de erros do PHP

Os registos de erros do PHP dão-te uma entrada informativa que descreve o que ocorreu. Aqui está um exemplo de entrada de log:

[13-Mar-2025 12:00:00 UTC] PHP Erro fatal: Exceção não capturada: Falha na ligação à base de dados em /var/www/html/index.php na linha 25

Desmontagem de registos:

• Marca o tempo: [13-Mar-2025 12:00:00 UTC]
• Tipo de erro: PHP Erro fatal
• Mensagem: Exceção não detectada: Falha na ligação à base de dados
• Número do ficheiro e da linha: /var/www/html/index.php na linha 25

Com estas entradas de registo, é possível rastrear os erros até à sua origem e corrigi-los adequadamente.

Melhores práticas de registo de erros do PHP

Terás de diferenciar as definições de Desenvolvimento e Produção da seguinte forma.

Na configuração do desenvolvimento, podes incluir o seguinte:

display_errors = Ligado
log_errors = On
relatório_de_erros = E_ALL

Na configuração da produção, podes incluir o seguinte:

display_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_NOTICE & ~E_DEPRECATED & ~E_STRICT

• Roda os ficheiros de registo: Evita que os ficheiros de registo se tornem demasiado grandes, utilizando ferramentas de rotação de registos, como o logrotate.
• Protege os arquivos de log: Limita o acesso ao ficheiro de registo através de permissões de ficheiro (por exemplo, chmod 600 /path/to/php_errors.log) para que não seja possível o acesso não autorizado.
• Monitoriza os registos regularmente: Utiliza software de monitorização como o Rollbar ou o Loggly para análise de registos em tempo real.
• Registro de log específico da estrutura (por exemplo, Laravel): Se estiveres a trabalhar com uma estrutura como Laravel ou Symfony, utiliza o seu registo incorporado para uma maior integração e flexibilidade.

O que é o PHP Debug Driven Development?

Antes, eu não tinha certeza sobre o termo desenvolvimento orientado por depuração (DDD), mas recebi essa idéia de um amigo depurador. O código dele continha vários pontos de interrupção, e ele passou por cada resposta de linha até obter a saída desejada.
Não te confundas com pontos de interrupção, pois vou demonstrá-los. O DDD tem um fluxo semelhante ao TDD, em que primeiro defines todas as técnicas de depuração do PHP para configuração e, em seguida, escreves o código para depurar se surgirem quaisquer erros.
Assim que tiveres uma ideia do DDD, deves aprender sobre o Xdebug, que te ajuda a compreender o conceito de desenvolvimento orientado para a depuração do PHP. Executar o PHP com o Xdebug dá-te uma visão completa dos erros, das respostas e da cobertura do código.

O que é o Xdebug?

Imagina que escreveste o teu código e que o código se avaria no momento em que o compilas. E a pior parte é que não consegues identificar o que correu mal. O Xdebug é a tua salvação.

O Xdebug é uma extensão PHP que ajuda os programadores a depurar e a suavizar o desenvolvimento dos seus projectos para procurar erros e resolvê-los. Actualiza a função var_dump() do PHP e adiciona traços de pilha para avisos, advertências, erros e excepções.

O Xdebug utiliza o protocolo de depuração DBGp e fornece capacidades de depuração e criação de perfis. Permite-nos adicionar pontos de interrupção e parar a execução do código em cada ponto de interrupção para ver o resultado das variáveis numa única iteração de código.

Assim, o Xdebug permite-te poupar o teu tempo, que de outra forma se perde na depuração do código. Sem o Xdebug, tens de atualizar a página para veres o resultado novamente. Também podes definir métodos independentes de pontos de interrupção para ver qual deles está a causar problemas.

Além disso, podes adicionar tantos pontos de interrupção quantos quiseres no código e utilizar um depurador de PHP para verificar cada código linha a linha.

Instalar o Xdebug no PHP

Agora é hora de instalar o Xdebug no PHP. Existem algumas opções através das quais podes instalar o Xdebug.

Janelas:

Para os utilizadores do Windows, o Xdebug fornece uma ferramenta de assistente através da qual podes transferir o ficheiro .dll relacionado. Para isso, primeiro, cria um ficheiro PHP na pasta e adiciona a seguinte linha de código:

<?php

phpinfo();

?>

Executa o ficheiro no browser. Verás as informações do PHP. Copia os detalhes e coloca-os na ferramenta do assistente e clica no botão Analisar a minha saída phpinfo() .

Isto dar-te-á o seguinte resultado:

Agora, transfere os ficheiros .dll e segue as instruções acima mencionadas para colocar os ficheiros no diretório xampp/php/ext. Em seguida, segue o passo 3 para ativar o Xdebug no ficheiro php.ini e, finalmente, reinicia o servidor Web.

MAC

Podes instalar o PHP7 Xdebug usando a extensão pecl:

instala o xdebug

Linux

Em distribuições Linux como a Debian, podes utilizar o Sudo para instalar o Xdebug em PHP:

sudo apt install php-xdebug;

Agora, abre o ficheiro etc/php/7.0/mods-available/xdebug.ini e adiciona o seguinte código para ativar o Xdebug:

xdebug.profiler_enable_trigger = 1

xdebug.profiler_enable = 0

xdebug.remote_enable = 1

xdebug.profiler_output_dir = "/tmp"

Agora, reinicia o servidor Apache2.

sudo service apache2 restart;

GIT

Também podes cloná-lo a partir do GitHub.

git clone git://github.com/xdebug/xdebug.git

Depois de instalar o Xdebug, abre o ficheiro php.ini e ativa a extensão.

zend_extension="xdebug.so"

Agora, verifica a versão do PHP usando o comando `php -v`. Verás a versão do Xdebug instalada com o PHP.

$ php -v

PHP 7.2.0RC6 (cli) (construído: 23 de novembro de 2017 10:30:56) ( NTS DEBUG )

Direitos autorais (c) 1997-2017 O Grupo PHP

Zend Engine v3.2.0-dev, Copyright (c) 1998-2017 Zend Technologies

  com Xdebug v2.6.0-dev, Copyright (c) 2002-2017, por Derick Rethans

Configura o Xdebug no VSCode

Se quiseres um fluxo de trabalho suave com o Xdebug, podes integrá-lo no teu IDE favorito, como o phpstorm, o Zend studio e o VScode. Vamos configurar o Xdebug no Visual Studio Code para depurar o PHP.

Existe uma popular extensão VSCode PHP chamada php debug. Podes encontrá-la na janela de extensões e instalá-la.

Após a instalação, tens de recarregar a janela do VSCode. Agora, executa novamente o método phpinfo(); em qualquer ficheiro PHP para verificar se o Xdebug está ativado ou não.

Agora clica no separador consola de depuração e clica em adicionar configuração.

Agora, tens de selecionar o ambiente que é o PHP. O VSCode irá agora adicionar um ficheiro launch.json no diretório raiz.

Por fim, adiciona a propriedade runtimeExecutable à lista depois de port:

"runtimeExecutable": "C:\\xampp\\php\\php.exe"

Salva o arquivo launch.json. Abre o separador modo de depuração e clica no botão verde de depuração para iniciar a opção de depuração.

Verás agora alguns itens na janela, através dos quais podes selecionar os registos que o Xdebugger irá mostrar:

• Avisos
• Avisos
• Erros
• Excepções
• Tudo

Navega para a secção Consola de depuração que te mostra os detalhes dos erros e os botões de execução de depuração na parte superior.

Neste ponto, podes adicionar pontos de interrupção nas linhas de código que precisas de depurar. Observe que o Xdebug adicionará o nome do script de depuração PHP com o número da linha na seção inferior esquerda:

Podes executar a aplicação no browser e depois ler o código linha a linha, para veres os erros e depurá-los corretamente. Além disso, tens de recordar algumas teclas de atalho para te deslocares pelas funções e linhas de código:

F5: Continua a depuração

F10: Passa por cima

F11: Entra em

Shift + F11: Sai da sala

Criação de perfil do Xdebug

O Xdebug também fornece criação de perfil de código, assim como outras ferramentas de criação de perfil, Blackfire e Tideways. Se quiseres usar a opção de criação de perfil, tens de a ativar no ficheiro php.ini.

xdebug.profiler_enable=1

xdebug.profiler_output_dir="C:\xampp\tmp"

Agora, abre um ficheiro e começa a introduzir todos os registos de criação de perfil.

Palavras finais

A depuração é um aspeto importante da codificação; sem ela, não podes dizer o que correu mal com o teu código.

Este artigo demonstrou como habilitar o PHP para depurar com o Xdebug e configurá-lo no VSCode. Também é possível integrá-lo ao Eclipse, ao PHPstorm e a outros IDEs.

Para aqueles que se aventuram no domínio da codificação extensiva, a configuração de um ambiente de depuração robusto é fundamental. Especialmente ao lidar com aplicações complexas que abrangem milhares de linhas, ter um depurador de PHP no local torna-se essencial para descobrir erros e sinais de aviso. Com a ajuda de ferramentas avançadas e a fiabilidade do alojamento web PHP, estás equipado para navegar nas complexidades da codificação e garantir uma experiência de desenvolvimento sem problemas.

Se houver algo que queiras saber mais, coloca as tuas dúvidas e sugestões na secção de comentários abaixo.

display_errors = Ligado
relatório_de_erros = E_ALL

log_errors = On
error_log = /caminho/para/arquivo_de_log.log

error_reporting(E_ALL);
ini_set('display_errors', 1);

zend_extension=xdebug  
xdebug.mode=debug  
xdebug.start_with_request=sim  
xdebug.client_host=127.0.0.1  
xdebug.client_port=9003

"php.executablePath": "C:/xampp/php/php.exe"

Salwa Mujtaba

Salwa Mujtaba é redatora de conteúdo técnico na Cloudways. Com uma sólida formação em Ciência da Computação e experiência anterior como líder de equipe em Operações da Cloudways, ela traz uma profunda compreensão da Plataforma Cloudways para sua escrita. Salwa cria conteúdo que simplifica conceitos complexos, tornando-os acessíveis e envolventes para os leitores. Quando não está a escrever, podes encontrá-la a apreciar boa música, a ler um livro ou a passar tempo de qualidade com a sua família.

Get Connected on: Twitter Community Forum