PHPStorm integrado com Docker e Xdebug

Otimizar o fluxo de desenvolvimento é uma busca constante para programadores que desejam aumentar a produtividade e a qualidade do código. Nesse contexto, a depuração (debug) de código em ambientes complexos, como os que utilizam contêineres, pode se tornar uma tarefa desafiadora. Felizmente, a integração entre ferramentas poderosas como o PHPStorm, Docker e Xdebug oferece uma solução robusta e eficiente para simplificar esse processo. Se você busca aprimorar suas habilidades de depuração e resolver problemas de forma mais ágil, este guia prático demonstrará passo a passo como configurar um ambiente de desenvolvimento PHP de alta performance.

❗️Pré-requisitos

Para o pleno aproveitamento deste material, é necessário que você tenha familiaridade com as seguintes tecnologias e ferramentas:

• Docker ≥ 20.10
• PHPStorm

👨‍💻 Preparando o ambiente

No post “PHPStorm: integrando Docker e PHPUnit” foi demonstrada uma integração utilizando o docker-compose. Neste artigo, adotaremos uma abordagem que utiliza a imagem Docker diretamente. Contudo, ambos os procedimentos são compatíveis, permitindo que você escolha o que melhor se adapta ao seu fluxo de trabalho.

Antes de configurar o Xdebug no PHPStorm, é imprescindível que você baixe uma imagem Docker que já tenha o Xdebug pré-configurado. Para isso, preparei uma imagem PHP projetada especificamente para ambientes de desenvolvimento. Execute o seguinte comando em seu terminal:

docker pull fabiojanio/php:8.4-cli-alpine3.22

Visite também o artigo: PHPStorm: integrando Docker e PHPUnit. Neste por sua vez é demonstrada uma integração via docker-compose, que também permite o uso do Xdebug.

Configurando o Xdebug no PHPStorm

IMPORTANTE: O Docker deve estar em execução para que o PHPStorm consiga identificar o processo.

Crie um novo projeto ou abra um existente no PHPStorm. Em seguida, acesse: PHPStorm > Preferences > Settings...:

Clique em PHP > …:

Clique em + > From Docker, Vagrant, VM, WSL, Remote...:

Selecione a opção Docker, o menu de marcação. Posteriormente, no campo Server, escolha a opção Docker no menu suspenso. Caso essa opção não exista, clique no botão New... :

A tela seguinte será exibida com os campos Server e PHP executable já preenchidos. Caso contrário, preencha-os manualmente, conforme a imagem:

Observe que, na tela acima, são exibidas as versões do PHP e do Xdebug mapeadas dentro do contêiner.

Ao prosseguir, na tela de configurações, em PHP language level selecione a versão 8.4. Isso é importante para que a IDE e o interpretador estejam alinhados quanto à versão do PHP em uso:

Ao clicar em OK,retornaremos à tela principal do PHPStorm. Neste momento, crie um arquivo chamado index.php e cole o código abaixo:

<?php

function calcularMedia($notas) {
    $soma = 0;  // BREAKPOINT 1: Aqui começa a função

    foreach ($notas as $nota) {
        $soma += $nota;  // BREAKPOINT 2: Iterar sobre as notas
    }

    $quantidade = count($notas);  // BREAKPOINT 3: Contar notas
    $media = $soma / $quantidade;  // BREAKPOINT 4: Calcular média

    return $media;
}

function aprovarOuReprovar($media) {
    $resultado = "";  // BREAKPOINT 5: Verificar resultado

    if ($media >= 7) {
        $resultado = "APROVADO";
    } else {
        $resultado = "REPROVADO";
    }

    return $resultado;
}

$notas = [6.5, 7.8, 8.2, 9.0, 7.5];  // BREAKPOINT 6: Array de notas
$media = calcularMedia($notas);        // BREAKPOINT 7: Chamar função calcularMedia
$status = aprovarOuReprovar($media);   // BREAKPOINT 8: Chamar função aprovarOuReprovar

echo "Notas do aluno: " . implode(", ", $notas) . "\n";
echo "Média: " . number_format($media, 2, ",", ".") . "\n";
echo "Status: " . $status . "\n";

Nos locais marcados como // BREAKPOINT, clique no número da linha para adicionar pontos de interrupção (breakpoints). Em seguida, clique no ícone de depuração (debug) e selecione o arquivo index.php. Veja como o resultado deve se parecer na imagem abaixo:

Neste momento, o depurador entrará em ação, exibindo as iterações na parte inferior da tela:

Observe que é possível visualizar uma variável de ambiente do PHP sendo exibida pelo Xdebug. Trata-se de um array de valores, que você pode expandir para ver os detalhes.

O menu de navegação está localizado no canto inferior direito, conforme demonstrado abaixo. Utilize o botão Step Into(indicado pela seta) para avançar nos passos de depuração:

Note que, à medida que os passos avançam, é possível observar os valores presentes nas variáveis. Adicione outros breakpoints ou remova os que não são mais necessários para uma depuração mais precisa.

Conclusão

Esta foi uma breve demonstração de como funciona a integração do Xdebug com o PHPStorm. Explore novas possibilidades e recursos avançados de depuração, como a criação de perfis (profiling) e o uso de condicionais de depuração para cenários mais específicos e controlados.