Dominando PHP_CodeSniffer e PHPStan: Qualidade Estática de Código em Projetos Reais Já leu

PHP_CodeSniffer: Implementando Padrões de Código

PHP_CodeSniffer (PHPCS) é uma ferramenta que detecta violações de padrões de código definidos. Ele analisa seu código estático, sem executá-lo, e identifica inconsistências em formatação, convenções de nomenclatura e aderência a standards como PSR-12. Funciona instalando-se via Composer e configurando regras que seu projeto deve seguir.

A instalação é simples: composer require --dev squizlabs/php_codesniffer. Após isso, você acessa o executável em vendor/bin/phpcs. O PHPCS varre seus arquivos e relata problemas encontrados. Por exemplo, um arquivo com indentação errada ou variável mal nomeada será sinalizado. Você também pode usar phpcbf (PHP Code Beauty and Fix) para corrigir automaticamente muitos erros.

Configuração Básica e Uso

Crie um arquivo phpcs.xml.dist na raiz do projeto para definir o comportamento padrão:

<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Meu Padrão">
    <description>Padrão de código para o projeto</description>

    <arg name="basepath" value="."/>
    <arg name="colors"/>
    <arg name="parallel" value="8"/>

    <file>src</file>
    <file>tests</file>

    <exclude-pattern>*/migrations/*</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>

    <rule ref="PSR12">
        <exclude name="Generic.WhiteSpace.DisallowTabIndent"/>
    </rule>
</ruleset>

Agora execute vendor/bin/phpcs para analisar o código. Para correção automática: vendor/bin/phpcbf. Exemplo prático:

// ❌ Código com problemas
class MinhaClasse{
function metodo(){
$variavel=10;
return $variavel;
}
}

// ✅ Depois de phpcbf
class MinhaClasse
{
    public function metodo()
    {
        $variavel = 10;
        return $variavel;
    }
}

PHPStan: Análise de Tipos e Lógica

PHPStan é uma ferramenta de análise estática que detecta erros sem executar o código, com foco em type-checking e bugs lógicos. Diferente do PHPCS que verifica formatação, PHPStan encontra erros reais: chamadas a métodos inexistentes, tipos incompatíveis, acesso a propriedades indefinidas. Funciona em múltiplos níveis (0 a 9), onde 0 é básico e 9 é rigoroso.

Instale com composer require --dev phpstan/phpstan. A configuração padrão já funciona, mas crie phpstan.neon para customização:

parameters:
    level: 7
    paths:
        - src
    excludePaths:
        - tests/fixtures
    ignoreErrors:
        - '#Access to undefined property#'

Execute com vendor/bin/phpstan analyse src. PHPStan detectará erros de tipo, propriedades indefinidas e lógica suspeita.

Exemplo Prático de Detecção

class Usuario
{
    private string $nome;

    public function __construct(string $nome)
    {
        $this->nome = $nome;
    }

    public function getNome(): string
    {
        return $this->nome;
    }
}

// ❌ PHPStan detecta erro de tipo
$usuario = new Usuario("João");
$email = $usuario->getEmail(); // Método não existe
echo $usuario->nome; // Propriedade privada
$valor = $usuario->getNome() + 5; // String + int inválido

// ✅ Código correto
$usuario = new Usuario("João");
$nome = $usuario->getNome();
echo $nome; // OK

PHPStan também valida docblocks e tipos de retorno. Se você declara que um método retorna string mas retorna null em algumas condições, PHPStan aviará. Isso evita surpresas em produção.

Integração com CI/CD e Automação

Para máxima eficiência, integre ambas as ferramentas no seu pipeline. Configure um arquivo composer.json com scripts de qualidade:

{
    "scripts": {
        "check-quality": [
            "@check-style",
            "@check-types"
        ],
        "check-style": "phpcs",
        "fix-style": "phpcbf",
        "check-types": "phpstan analyse"
    }
}

Agora execute composer check-quality localmente antes de fazer push. Para GitHub Actions, crie .github/workflows/quality.yml:

name: Code Quality

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      - run: composer install

      - run: composer check-style

      - run: composer check-types

Desse modo, todo PR é analisado automaticamente. Desenvolvedores recebem feedback imediato se código violar padrões ou conter erros potenciais. Isso melhora drasticamente a qualidade e reduz bugs em produção.

Extensões Úteis

PHPStan possui extensões para frameworks. Se usar Laravel, instale phpstan/phpstan-laravel. Para Symfony, há phpstan/phpstan-symfony. Essas extensões entendem as convenções do framework e reduzem falsos positivos. Use composer require --dev phpstan/phpstan-laravel e configure em phpstan.neon:

includes:
    - vendor/phpstan/phpstan-laravel/extension.neon

Conclusão

PHP_CodeSniffer e PHPStan são complementares: PHPCS garante consistência visual e aderência a padrões (PSR), enquanto PHPStan previne erros reais de lógica e tipo. Juntos, formam uma defesa robusta contra bugs e código frágil. Primeiro aprendizado: Use ambas as ferramentas no seu workflow — uma não substitui a outra. Segundo ponto: Configure-as no CI/CD para automatizar validação. Terceiro: Comece com níveis moderados (PSR-12, nível 7 do PHPStan) e aumente gradualmente conforme o projeto matura.

Referências

• PHP_CodeSniffer - Documentação Oficial
• PHPStan - Documentação
• PSR-12: Extended Coding Style Guide
• Static Analysis in PHP - Martin Fowler