Se você trabalha com PHP, provavelmente já passou pela frustração de descobrir um erro em produção que poderia ter sido evitado com uma simples checagem de tipo ou verificação de variável. O PHP é uma linguagem flexível, mas essa mesma liberdade pode levar a “bugs silenciosos”.

É aqui que entra o PHPStan.

O que é o PHPStan? Link para o cabeçalho

O PHPStan é uma ferramenta de análise estática para PHP. Diferente de um teste unitário, que precisa executar o seu código para verificar se ele funciona, o PHPStan “lê” o seu código sem executá-lo.

Ele constrói um modelo mental da sua aplicação — entendendo classes, métodos, propriedades e tipos — e aponta inconsistências antes mesmo de você abrir o navegador. É como ter um revisor de código experiente olhando cada linha que você escreve, 24 horas por dia.

Mão na massa: Aplicando o PHPStan em um projeto Link para o cabeçalho

Vamos ver como é simples configurar o PHPStan em um projeto PHP puro.

1. Instalação via Composer Link para o cabeçalho

Certifique-se de estar na raiz do seu projeto e execute:

composer require --dev phpstan/phpstan

2. Criando um código de exemplo (com erros) Link para o cabeçalho

Imagine um arquivo chamado src/Calculadora.php:

<?php

class Calculadora {
    public function somar($a, $b) {
        return $a + $b;
    }
}

$calc = new Calculadora();
// Erro: passando string onde deveria ser número
echo $calc->somar(10, "cinco");

3. Executando a análise Link para o cabeçalho

Rode o comando do PHPStan apontando para a pasta do seu código:

./vendor/bin/phpstan analyse src --level=5

Nota: O --level vai de 0 (básico) a 10 (mais rigoroso).

O PHPStan irá retornar algo como:

Line 11: Parameter #2 $b of method Calculadora::somar() expects int|float, string given.

Ele identificou que você está tentando somar um número com uma string, algo que causaria um erro ou comportamento inesperado no PHP moderno.

4. O arquivo de configuração (phpstan.neon) Link para o cabeçalho

Para não ter que digitar os parâmetros sempre, crie um arquivo phpstan.neon na raiz:

parameters:
    level: 8
    paths:
        - src

Agora basta rodar apenas ./vendor/bin/phpstan.

Por que adotar o PHPStan? Link para o cabeçalho

  • Encontra bugs antes dos testes: Detecta erros em caminhos de código que você raramente executa.

  • Melhora a qualidade do código: Força você a escrever códigos mais tipados e organizados.

  • Não requer execução: Não precisa de banco de dados, servidor web ou mocks para rodar.

  • Integração com CI: Pode ser configurado para bloquear commits que não passam na análise, garantindo que nenhum código “sujo” entre no seu repositório.