Configurando um Ambiente de Desenvolvimento Local de WordPress com Docker, Xdebug e PhpStorm

Com Docker Compose, Xdebug e PhpStorm, você pode criar um ambiente de desenvolvimento local reproduzível, isolado e facilmente gerenciável que espelha um servidor de produção, melhorando a qualidade dos seus projetos WordPress.

Olá, desenvolvedores e usuários avançados de WordPress! Hoje, estou animado para compartilhar um tutorial abrangente, mas simples, sobre como configurar um ambiente de desenvolvimento local de WordPress usando Docker Compose. Tendo recentemente me tornado parte da equipe dinâmica da OnTheGoSystems, decidi trazer minha zona de conforto comigo, que é o que essa configuração representa.

O objetivo era simples: desenvolver uma configuração onde eu pudesse ter controle granular sobre minhas ferramentas de desenvolvimento, integrando Xdebug e WP-CLI com a imagem oficial do Docker de WordPress. Essa configuração não é sobre reinventar a roda, mas sobre personalizá-la para alinhar com preferências e estilos de trabalho individuais. Espero que este guia seja benéfico para você na configuração de um ambiente semelhante, aprimorando sua jornada no desenvolvimento de WordPress.

Pré-requisitos

Para aproveitar ao máximo este tutorial, você precisará ter as seguintes dependências instaladas:

Docker: Usaremos Docker como nossa ferramenta principal para criar, implantar e executar aplicativos usando contêineres. Ele nos permite empacotar um aplicativo com todas as partes necessárias em um contêiner e enviá-lo como um único pacote. O que torna o Docker ainda mais poderoso é sua promessa de controle granular, permitindo-nos definir precisamente cada aspecto da configuração do nosso aplicativo. Esse controle ajuda a criar um ambiente de desenvolvimento que atende exatamente às nossas necessidades.
Extensão Xdebug para Chrome: Esta extensão de navegador nos ajudará a percorrer nosso código, identificar bugs e melhorar a qualidade geral dos nossos projetos WordPress.
PhpStorm: Um IDE inteligente e completo para PHP desenvolvido pela JetBrains. Ele fornece um editor para PHP, HTML e JavaScript com análise de código em tempo real e refatoração automatizada para essas linguagens.

Por que Docker, Xdebug e PhpStorm?

Nosso objetivo é estabelecer um ambiente de desenvolvimento local de WordPress que seja isolado, reproduzível e facilmente gerenciável. O Docker forma a espinha dorsal dessa configuração, fornecendo a infraestrutura para conter e gerenciar nosso aplicativo. Xdebug e PhpStorm são as peças complementares desse quebra-cabeça, oferecendo capacidades aprimoradas de desenvolvimento e depuração de código PHP.

Nossa jornada começará com a criação de um Dockerfile que estende a imagem oficial do Docker de WordPress. Vamos aprimorar essa imagem incorporando Xdebug e WP-CLI, ferramentas instrumentais em nossas tarefas de desenvolvimento e depuração de WordPress.

Em seguida, redigiremos um arquivo Docker Compose para orquestrar dois serviços principais: WordPress e MySQL. E acredite ou não, isso é basicamente tudo!

A beleza dessa configuração é que ela resulta em um ambiente de desenvolvimento local que não apenas espelha um servidor de produção, mas também é facilmente replicável. Isso significa que podemos duplicar a configuração exata em vários ambientes ou máquinas com facilidade, garantindo consistência e reduzindo problemas relacionados à configuração.

Tutorial Passo a Passo

Passo 1: O Dockerfile

Nossa jornada começa com a criação de um novo Dockerfile. Este arquivo instrui o Docker sobre como construir nossa imagem. Aqui está a configuração básica com a qual eu geralmente começo:

# Use the official WordPress image as a parent image
FROM wordpress:latest

# Install Xdebug
RUN pecl install xdebug 

# Install WP-CLI
RUN curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && \
    chmod +x wp-cli.phar && \
    mv wp-cli.phar /usr/local/bin/wp

# Copy xdebug.ini into the container
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Neste Dockerfile, começamos a partir da imagem oficial de WordPress. Em seguida, instalamos Xdebug e WP-CLI separadamente para clareza e manutenção. O arquivo de configuração do Xdebug (xdebug.ini) é copiado para o diretório apropriado no contêiner. Isso forma a base da minha configuração padrão para um ambiente de desenvolvimento local de WordPress.

Passo 2: O Arquivo de Configuração do Xdebug (xdebug.ini)

Agora que temos o Xdebug instalado em nossa imagem Docker, precisamos configurá-lo para funcionar em nosso ambiente de desenvolvimento local. Isso envolve a criação de um arquivo xdebug.ini com as seguintes configurações:

ini
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_port=9003
xdebug.start_with_request=yes

Essas configurações habilitam a extensão Xdebug, configuram para iniciar a depuração com cada solicitação e definem a porta do cliente à qual ele deve se conectar (neste caso, 9003). Você pode ter notado que ainda não especificamos um client_host, mas não se preocupe, ele entrará em jogo muito em breve em nosso processo de configuração.

Passo 3: O Arquivo Docker Compose

Em seguida, criaremos um arquivo docker-compose.yml que configura nossos serviços de WordPress e MySQL:

yaml
version: '3'
services:
  # MySQL Service
  mysql:
    image: mysql:latest
    container_name: mysql_container
    restart: always
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
  
  # WordPress Service
  wordpress:
    depends_on: 
      - mysql
    image: wordpress:latest
    container_name: wp_container
    volumes:
      - ./wp_data:/var/www/html
    environment:
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DEBUG: 1
      XDEBUG_CONFIG: client_host=host.docker.internal
    ports:
      - "8000:8000"

volumes:
  db_data:

Neste arquivo, definimos dois serviços – MySQL e WordPress. Ambos os serviços têm nomes de contêineres únicos, para facilitar a referência e o gerenciamento.

A diretiva restart: always garante que o serviço sempre reinicie se parar inesperadamente. Se for interrompido manualmente, ele será reiniciado apenas quando o contêiner for reiniciado manualmente.

O serviço MySQL monta um volume Docker (db_data), garantindo armazenamento persistente mesmo se o contêiner for excluído. Para o serviço WordPress, estamos montando um diretório local (./wp_data) no contêiner. Isso significa que quaisquer alterações nos arquivos do WordPress em nosso sistema local serão refletidas no contêiner.

Adicionamos duas variáveis de ambiente adicionais para o serviço WordPress – WORDPRESS_DEBUG para habilitar a depuração do WordPress e XDEBUG_CONFIG para especificar o host do cliente para o Xdebug. O client_host está configurado para host.docker.internal, que é um nome DNS especial que direciona para o endereço IP interno do host, permitindo que o Xdebug se comunique com nosso IDE no host.

Observe que a configuração client_host é adaptada para Windows e macOS. Para Linux, uma alternativa comum é substituir host.docker.internal pelo endereço IP real da sua máquina, que pode ser obtido através do comando de terminal ip addr show.

Passo 4: Executando Seu Ambiente de Desenvolvimento Local do WordPress

Uma vez que seu Dockerfile, arquivo de configuração do Xdebug e arquivo Docker Compose estejam prontos, é hora de dar vida ao seu ambiente de desenvolvimento local do WordPress.

Para fazer isso, basta navegar até o diretório que contém seu arquivo Docker Compose no terminal e executar o seguinte comando:

bash
docker-compose up -d

Este comando instruirá o Docker a iniciar seus serviços em segundo plano.

Após a execução bem-sucedida, você terá um site WordPress rodando em sua máquina local, acessível via http://localhost:8000. Qualquer alteração que você fizer nos arquivos PHP do WordPress agora será refletida neste site, oferecendo uma maneira fácil e eficaz de desenvolver e depurar sua aplicação WordPress.

Além disso, seu serviço MySQL também estará em funcionamento, acessível na porta 3306. Isso fornece um banco de dados MySQL totalmente funcional para sua aplicação WordPress, replicando um ambiente realista para suas necessidades de desenvolvimento.

Passo 4.5: Passo Bônus – Adicionando o Arquivo phpinfo.php

Para aqueles que querem se aprofundar um pouco mais na configuração do PHP, podemos introduzir um arquivo phpinfo.php em nossa imagem Docker. Quando acessado, este arquivo apresentará uma visão geral abrangente das suas configurações de PHP.
Para adicionar o arquivo phpinfo.php, você precisará primeiro criá-lo no mesmo diretório que seu Dockerfile. O arquivo deve conter o seguinte código PHP:

<?php phpinfo(); ?>

Em seguida, adicione a seguinte linha ao seu Dockerfile:

# Bonus: Copy phpinfo.php into the container
COPY phpinfo.php /var/www/html/phpinfo.php

Este comando copiará o arquivo phpinfo.php para o diretório raiz do WordPress dentro da imagem Docker.

Para garantir que essas alterações entrem em vigor, você precisará reconstruir sua imagem Docker e reiniciar os serviços do Docker Compose. Execute os seguintes comandos no seu terminal:

bash
docker-compose down
docker-compose up -d --build

O comando docker-compose down para e remove seus contêineres Docker atuais. Em seguida, docker-compose up -d –build reconstrói a imagem Docker com o novo arquivo phpinfo.php adicionado e reinicia seus serviços WordPress e MySQL em segundo plano.
Agora você pode acessar o arquivo phpinfo.php navegando para http://localhost:8000/phpinfo.php no seu navegador web. Aqui, você verá uma página detalhada descrevendo sua configuração PHP, que pode ser um recurso valioso para depuração e verificação.

Passo 5: Comece a Depurar

Agora que você configurou seu ambiente de desenvolvimento local do WordPress com Docker, Xdebug e PhpStorm, você pode começar a depurar seu site WordPress. Aqui está um resumo rápido de como começar:

Configurar o Xdebug no PhpStorm: Abra o PhpStorm e vá para Arquivo → Configurações (Preferências no Mac) → Linguagens & Frameworks → PHP → Depuração. Na seção Xdebug, certifique-se de que a Porta de Depuração esteja configurada para 9003 e a opção Pode aceitar conexões externas esteja marcada.
Adicionar um Servidor PhpStorm: Navegue para PHP → Servidores. Adicione um novo servidor com o nome wordpress e o host localhost. Defina a porta para 8000. Certifique-se de que os mapeamentos de caminho estejam configurados corretamente – o caminho absoluto no servidor para a pasta wp_data deve ser /var/www/html.
Instalar a extensão Xdebug helper: Instale a extensão Xdebug helper para o Google Chrome. Uma vez instalada, clique no ícone do bug e defina a chave IDE para PHPSTORM.
Começar a escutar conexões de Debug PHP: No PhpStorm, clique no ícone de bug no canto superior direito para começar a escutar conexões de Debug PHP.
Iniciar Debugging: Com os passos anteriores concluídos, você está pronto para começar a depurar sua aplicação WordPress. Basta definir seus pontos de interrupção no PhpStorm conforme necessário e, em seguida, recarregar seu site. Feliz depuração!

Conclusão

Ao concluirmos este tutorial, espero que ele se torne um recurso valioso para você, assim como foi para mim em minha jornada. A capacidade de personalizar esta configuração – como fizemos ao adicionar o arquivo phpinfo.php – abre uma infinidade de possibilidades, tornando nosso processo de desenvolvimento mais robusto e eficiente. Todo o código está disponível neste repositório GitHub. Não hesite em puxá-lo, experimentá-lo e sugerir melhorias!

Eu pessoalmente uso um sistema operacional Ubuntu, mas a beleza desta configuração é que graças ao Docker isso não importa! Graças ao fato de que o Docker pode rodar em qualquer sistema operacional igualmente, seja você preferir macOS, Windows ou Linux, a configuração e o uso são os mesmos!

Obrigado por me acompanhar neste tutorial. Espero ouvir de você sobre suas experiências ou quaisquer sugestões que possa ter para melhorar ainda mais esta configuração. Lembre-se, o crescimento prospera com o conhecimento compartilhado e o espírito de colaboração.

Feliz codificação, e vamos continuar criando experiências incríveis com WordPress juntos!

How can we make WPML better for you?

Share your thoughts and comments about our plugin, documentation, or videos by booking a Zoom call with Agnes, our Client Advocate. Your feedback matters and helps us improve.

Book a call with Agnes