PHP-CS-Fixer para PHP: guia completo com exemplos práticos

1. O que é e para que serve

PHP-CS-Fixer (PHP Coding Standards Fixer) é uma ferramenta poderosa para formatar automaticamente código PHP de acordo com padrões de codificação definidos. Ele analisa o código-fonte, identifica violações de regras de formatação (indentação, espaços, quebras de linha, ordem de imports, uso de sintaxes curtas, etc.) e as corrige automaticamente. A biblioteca é indispensável em projetos PHP modernos, especialmente no desenvolvimento em equipe.

Por que usar? Primeiro, para manter um estilo de código uniforme na equipe. Quando vários desenvolvedores trabalham no mesmo projeto, cada um pode ter seus próprios hábitos de formatação. O PHP-CS-Fixer resolve isso, padronizando todo o código. Segundo, economiza tempo em code review: em vez de discutir indentação e espaços, os desenvolvedores podem focar na lógica e arquitetura. Terceiro, a formatação automática evita alterações "ruidosas" em commits, onde a correção de uma linha pode mudar a formatação do arquivo inteiro.

O PHP-CS-Fixer suporta dezenas de regras integradas (mais de 100) e permite criar regras personalizadas. A ferramenta é facilmente integrável em pipelines CI/CD, sistemas de controle de versão (via hooks pre-commit) e IDEs. É compatível com PSR-1, PSR-2, PSR-12, Symfony, Doctrine e outros padrões populares de codificação.

2. Instalação

O PHP-CS-Fixer é instalado via Composer, o gerenciador de dependências do PHP. Recomenda-se instalá-lo globalmente ou como dependência de desenvolvimento no projeto.

# Instalação global (recomendado para usar em qualquer projeto)
composer global require friendsofphp/php-cs-fixer

# Instalação como dependência de desenvolvimento em um projeto específico
composer require --dev friendsofphp/php-cs-fixer

# Verificar instalação
php-cs-fixer --version

Após a instalação global, certifique-se de que o diretório ~/.composer/vendor/bin (ou %USERPROFILE%\AppData\Roaming\Composer\vendor\bin no Windows) foi adicionado à variável de ambiente PATH.

3. Início rápido — exemplo mínimo funcional

Crie um arquivo exemplo.php com código "bagunçado":

<?php
$nome = "João";
$idade=30;
function saudacao($nome){
echo "Olá, ".$nome;
}
saudacao($nome);

Agora formate-o com o PHP-CS-Fixer:

php-cs-fixer fix exemplo.php --rules=@PSR12

Após a execução, o arquivo ficará assim:

<?php

$nome = 'João';
$idade = 30;

function saudacao($nome): void
{
    echo 'Olá, '.$nome;
}

saudacao($nome);

Como você pode ver, o PHP-CS-Fixer adicionou espaços ao redor do operador de atribuição, substituiu aspas duplas por simples (quando não há interpolação), adicionou o tipo de retorno : void, formatou as chaves e adicionou linhas em branco para melhorar a legibilidade.

4. Principais métodos/funções/classes

4.1. PhpCsFixer\Config::create()

Assinatura: public static Config::create(): Config

O que faz: Cria uma nova instância de configuração para definir as regras de formatação.

<?php
use PhpCsFixer\Config;

$config = Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/src')
    );

4.2. PhpCsFixer\Finder::create()

Assinatura: public static Finder::create(): Finder

O que faz: Cria um objeto para localizar arquivos PHP que precisam ser formatados.

<?php
use PhpCsFixer\Finder;

$f