PHPStorm: integrando Docker e PHPUnit

O uso de contêineres é uma prática que adotei para quase todas as minhas atividades de desenvolvimento. Esse hábito simplifica meu dia a dia e evita retrabalho. Ao desenvolver no ecossistema PHP, por exemplo, inicio um contêiner, conecto-me a ele e utilizo o Composer para gerenciar dependências, configurar o autoload e executar testes (unitários, de integração, etc.). Essa rotina tornou-se ainda mais eficiente com a integração do PHPStorm com o Docker, que permite rodar testes com PHPUnit de forma mais simples e controlada.

❗️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

Utilizarei o Laravel Framework para agilizar a demonstração. No entanto, os passos aqui apresentados são agnósticos e podem ser aplicados a outros projetos PHP.

Baixando o Laravel

Como mencionei, eu não tenho o PHP instalado diretamente na minha máquina. Para contornar isso, utilizo o Docker. Execute o comando abaixo para baixar o Laravel:

docker run \
    --rm \
    -v $(pwd):/app \
    fabiojanio/php:8.4-cli-alpine3.22 composer create-project --prefer-dist laravel/laravel

A instrução acima utiliza a imagem pública fabiojanio/php:8.4-cli-alpine3.22 para criar um contêiner temporário que baixa e instala o Laravel. Ao final do processo, o contêiner é automaticamente removido.

Subindo a Aplicação

Agora, vamos usar o docker-compose para simplificar ainda mais o processo. Acesse o diretório do projeto, que por padrão é laravel uma vez que não atribuímos nenhum outro nome ao rodar o comando anterior:

cd laravel

Crie um arquivo chamado docker-compose.yml na raiz do projeto com o seguinte conteúdo:

version: '3'

services:
  php:
    container_name: php
    image: fabiojanio/php:8.4-cli-alpine3.22
    volumes:
      - ./:/app
    working_dir: /app
    restart: on-failure
    user: www-data
    ports:
      - "8080:80"
    command: >
      sh -c "php artisan serve --host=0.0.0.0 --port=80"

A configuração acima é uma versão resumida de um exemplo que publiquei no GitHub: https://github.com/docker-sources/php/blob/main/docker-compose.yml

Para iniciar a aplicação, execute:

docker-compose up -d

Sua aplicação estará acessível em http://localhost:8080.

👨‍💻 Configurando o PHPStorm para Usar Docker + PHPUnit

Abra o projeto no PHPStorm e acesse: PHPStorm > Preferences > Settings...:

No painel de configurações, procure por PHP > Test Frameworks. Se houver uma configuração local do PHPUnit que não esteja em uso, você pode removê-la para evitar confusão. Em seguida, clique no ícone +:

No menu que se abre, selecione PHPUnit by Remote Interpreter:

Clique nos três pontos (…) para configurar um novo interpretador:

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

Selecione Docker Compose. O PHPStorm deverá preencher o campoServer automaticamente. Caso contrário, clique em New.... O campo Configuration files ser'a preenchido com o docker-compose.yml do projeto. Em Service, escolha o contêiner que contém o interpretador PHP (neste caso, php). Por fim, clique em OK:

Na tela seguinte, em Lifecycle, marque a opção Connect to existing container (docker-compose exec)e finalize clicando em OK:

Com essa opção, a IDE tentará se conectar a uma instância existente do contêiner. Se não houver uma, a IDE criará uma nova. Note que a IDE já identificou a versão do PHP da imagem Docker.

Na próxima janela, selecione o interpretador php que acabamos de configurar e clicar em OK:

As configurações da próxima janela provavelmente já estarão preenchidas. Caso contrário, preencha-as manualmente, conforme a imagem abaixo:

O /app é o workerdir configurado na imagem Docker. Se você estiver usando outra imagem ou alterou essa configuração, lembre-se de ajustá-la aqui.

Agora, acesse PHPStorm > Preferences > PHP e configure o interpretador da CLI conforme a imagem abaixo:

Essa configuração define o interpretador padrão para a CLI do PHP. Sem isso, você será solicitado a escolher um interpretador toda vez que executar um teste.

Com tudo configurado, existem várias maneiras de executar um teste. Uma delas é abrir o arquivo de teste e clicar nos ícones de execução (setas verdes):

Como a imagem Docker utilizada também possui o Xdebug instalado, pode ser que uma janela pop-up apareça ao executar o teste. Se isso ocorrer, basta clicar em Rua 'ExampleTest (PHPUnit)':

Para rodar todos os testes, clique com o botão direito no diretório tests e selecione Run 'tests (PHPUnit)', ou utilize a configuração de execução no canto superior diretio e clique no botão play:

Existem outras formas de rodar os testes, como usar o modo watch do PHPStorm para executar os testes automaticamente ao salvar alterações.

Essa integração é simples, mas poupa um tempo valioso no dia a dia. Em vez de digitar comandos para executar os testes, você pode simplesmente escolher o que testar e executar com um clique.

✌️Conclusão

Explore sua IDE para descobrir os recursos, facilidades e integrações que ela oferece. Embora seja importante saber como fazer as coisas manualmente pela linha de comando, especialmente durante o aprendizado, isso nem sempre é prático no dia a dia. Busque maneiras de simplificar sua rotina, integrando ferramentas e automatizando tarefas.

Não tenha medo de explorar!