PHPStan: O que é, vantagens e como usar em projetos Laravel

Se você é desenvolvedor PHP, já deve ter se deparado com situações em que bugs ou erros de tipo passaram despercebidos até chegarem à produção. Para evitar esses problemas, ferramentas de análise estática como o PHPStan são essenciais. Neste post, vamos explorar o que é o PHPStan, suas vantagens e como configurá-lo em um projeto Laravel.

Primeiro: O que é o PHPStan?

O PHPStan é uma excelente ferramenta de análise estática para PHP. Ele analisa o código em busca de erros comuns, como chamadas a métodos inexistentes, tipos incorretos, variáveis não definidas e muito mais, sem precisar executar o código. Ele é altamente configurável e pode ser integrado facilmente em projetos de qualquer tamanho.

O PHPStan é especialmente útil em projetos grandes, onde a complexidade do código pode levar a erros difíceis de detectar manualmente. Ele ajuda a garantir que o código seja mais seguro, legível e mantenível.

Para saber mais sobre, só dar uma olhada na documentação oficial – PHPStan

Vantagens de usar o PHPStan

Detecção precoce de erros
O PHPStan identifica problemas no código antes que ele seja executado, reduzindo a chance de bugs em produção.
Melhoria da qualidade do código
Ele incentiva boas práticas de programação, como o uso de tipos corretos e a escrita de código mais seguro.
Integração com frameworks populares
O PHPStan funciona perfeitamente com frameworks como Laravel, Symfony e outros, graças a extensões como o Larastan.
Configuração flexível
Você pode ajustar o nível de rigor da análise, desde verificações básicas até análises avançadas de tipos genéricos e inferência de tipos.
Economia de tempo
Ao detectar erros automaticamente, o PHPStan reduz a necessidade de testes manuais e depuração

Como usar o PHPStan em um projeto Laravel

Agora que você conhece as vantagens, vamos ver como configurar e usar o PHPStan em um projeto Laravel.

Passo 1: Instalação

Primeiro, instale o Larastan (extensão do PHPStan para Laravel) via Composer:

composer require --dev nunomaduro/larastan

Passo 2: Configuração básica

Crie um arquivo de configuração chamado phpstan.neon na raiz do seu projeto. Esse arquivo define as regras e opções de análise. Aqui está um exemplo básico:

includes:
    - ./vendor/nunomaduro/larastan/extension.neon

parameters:
    paths:
        - app/
    level: 6

paths: Define os diretórios que o PHPStan deve analisar (por exemplo, app/).
level: Define o nível de rigor da análise. O nível 6 é um bom ponto de partida, mas você pode ajustar conforme necessário (níveis vão de 0 a 9).

Passo 3: Executando o PHPStan

Para rodar o PHPStan, use o seguinte comando no terminal:

./vendor/bin/phpstan analyse

Se o projeto for grande e o PHPStan estourar o limite de memória, você pode aumentar o limite com a opção --memory-limit:

./vendor/bin/phpstan analyse --memory-limit=512M

Passo 4: Ajustando o nível de análise

O PHPStan permite ajustar o nível de análise de 0 a 9. Quanto maior o nível, mais rigorosa será a verificação. Por exemplo, para usar o nível máximo:

parameters:
    level: 9

Se você estiver começando, pode começar com um nível mais baixo (como 3 ou 4) e aumentar gradualmente conforme o código melhora.

Passo 5: Ignorando erros específicos

Às vezes, o PHPStan pode apontar erros que você quer ignorar temporariamente. Para isso, use a opção ignoreErrors no arquivo de configuração:

parameters:
    ignoreErrors:
        - '#Call to an undefined method .*#'

Isso ignora erros relacionados a chamadas de métodos indefinidos.

Passo 6: Integrando ao CI/CD

Para garantir que o código sempre passe pela análise do PHPStan, você pode integrá-lo ao seu pipeline de CI/CD. Por exemplo, no GitHub Actions, adicione um passo como este:

- name: Run PHPStan
  run: ./vendor/bin/phpstan analyse --memory-limit=512M

Dicas para aproveitar ao máximo o PHPStan

Use tipos generics (PHP 7.4+)
O PHPStan é capaz de analisar tipos genéricos em coleções e outras estruturas. Certifique-se de usar anotações de tipo corretamente.
Adicione anotações de tipo
Quanto mais informações de tipo você fornecer ao PHPStan, melhor será a análise. Use @param, @return e @var sempre que possível.
Execute o PHPStan regularmente
Adicione o PHPStan ao seu fluxo de trabalho diário para garantir que o código esteja sempre em boas condições.
Combine com outras ferramentas
Use o PHPStan junto com outras ferramentas como o Pint (para formatação) e o PHPUnit (para testes) para garantir a máxima qualidade do código.

O PHPStan é uma ferramenta poderosa para melhorar a qualidade do código em projetos PHP, especialmente em projetos grandes e complexos. Com sua capacidade de detectar erros antes que eles cheguem à produção, ele se torna um aliado indispensável para qualquer desenvolvedor.

Se você ainda não está usando o PHPStan no seu projeto Laravel, experimente seguir este tutorial e veja como ele pode transformar a maneira como você escreve e mantém seu código.