PHP CS Fixer: Guia completo para instalação, configuração e uso

Instalando o PHP CS Fixer

Para iniciar a instalação do PHP CS Fixer, a abordagem mais comum envolve o uso do Composer, especialmente em projetos PHP. Sendo assim, execute o comando composer require --dev friendsofphp/php-cs-fixer na raiz do seu projeto. Essa prática assegura que as versões estejam sob controle no arquivo composer.json, facilitando futuras atualizações com composer update friendsofphp/php-cs-fixer. Por outro lado, se você deseja um acesso global em múltiplos projetos, pode optar por composer global require friendsofphp/php-cs-fixer e adicionar o diretório bin global ao seu PATH.

Uma alternativa para a instalação é o uso do arquivo PHAR. Para isso, baixe a versão mais recente diretamente do repositório oficial no GitHub com o comando wget https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/releases/download/v3.13.0/php-cs-fixer.phar -O php-cs-fixer. Em seguida, torne o arquivo executável utilizando chmod +x php-cs-fixer e mova-o para /usr/local/bin/, garantindo que esteja disponível em todo o sistema. Para confirmar a instalação, execute ./php-cs-fixer --version.

Além disso, os usuários que utilizam Docker podem extrair a imagem oficial com docker pull friendsofphp/php-cs-fixer. Para executar a ferramenta em contêineres, utilize o comando docker run --rm -it -v $(pwd):/code friendsofphp/php-cs-fixer fix /code. Essa abordagem oferece isolamento de dependências e se adapta facilmente a ambientes de CI, evitando a necessidade de instalações locais de PHP.

Configurando o PHP CS Fixer

Para configurar o PHP CS Fixer, crie um arquivo de configuração denominado .php-cs-fixer.php ou .php-cs-fixer.dist.php na raiz do seu projeto. Dessa forma, é possível definir conjuntos de regras utilizando a sintaxe PHP, o que proporciona maior flexibilidade. Como resultado, você pode iniciar com uma configuração básica como a seguinte:

setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
        'binary_operator_spaces' => ['default' => 'align_single_space'],
    ])
    ->setFinder(
        PhpCsFixerFinder::create()
            ->in(__DIR__)
            ->exclude(['vendor', 'var'])
    );

Personalize as regras conforme as necessidades do seu projeto. Você pode habilitar predefinições como @Symfony ou @PhpCsFixer e, em seguida, substituir opções específicas, como no_unused_imports ou ordered_imports. Por conseguinte, é possível controlar regras mais arriscadas utilizando setRiskyAllowed(true) ao aplicar transformações como strict_param.

Além disso, é recomendável integrar configurações de cache para acelerar execuções em ciclos repetidos: ->setCacheFile(__DIR__.'/.php-cs-fixer.cache'). Exclua diretórios como node_modules ou crie saídas por meio da instância do Finder. Para projetos monorepo, configure múltiplos localizadores direcionados a pacotes específicos.

Usando PHP CS Fixer de forma eficaz

Para executar correções, utilize o comando vendor/bin/php-cs-fixer fix. Você pode segmentar caminhos específicos com vendor/bin/php-cs-fixer fix src/ --rules=@PSR12. Execute testes preliminares com o sinalizador --dry-run para visualizar as alterações sem modificar os arquivos: vendor/bin/php-cs-fixer fix --dry-run --diff.

Durante a solução de problemas, aplique regras individuais utilizando vendor/bin/php-cs-fixer fix --rules=no_trailing_whitespace. O formato de diretórios inteiros respeita os padrões do .gitignore por padrão. Além disso, o processamento paralelo pode acelerar grandes bases de código através do uso de --parallel.

Para integrar com os fluxos de trabalho do Git, utilize ganchos de pré-confirmação. Adicione um script ao seu arquivo composer.json da seguinte forma:

"scripts": {
    "cs-fix": "php-cs-fixer fix",
    "cs-check": "php-cs-fixer fix --dry-run --diff"
}

Além disso, você pode executar verificações em pipelines de CI utilizando GitHub Actions ou GitLab CI. É importante armazenar em cache o binário e a configuração da ferramenta para reduzir o tempo de compilação. Combine essa abordagem com ferramentas como PHPStan ou Psalm para uma análise estática mais robusta.

Técnicas avançadas de correção de PHP CS

Para estender a funcionalidade do PHP CS Fixer, você pode implementar fixadores personalizados através da interface PhpCsFixerFixerFixerInterface. Registre regras personalizadas no arquivo de configuração para atender a padrões específicos de domínio. Em contrapartida, analise as prioridades das regras para resolver conflitos quando múltiplas regras visam o mesmo segmento de código.

Aproveite configurações específicas do ambiente utilizando getenv() dentro do arquivo .php-cs-fixer.php. Você pode alternar conjuntos de regras entre ramos de desenvolvimento e produção. Para monitorar o desempenho, utilize a opção --verbose para identificar regras que podem ser lentas em arquivos grandes.

Por fim, combine o PHP CS Fixer com EditorConfig para garantir um recuo consistente entre diferentes ferramentas. Os plug-ins IDE para PhpStorm e VS Code oferecem visualizações de correções em tempo real. Agende verificações completas periódicas para manter a qualidade do código a longo prazo, evitando intervenções manuais.

Perguntas Frequentes

O que é o PHP CS Fixer?

O PHP CS Fixer é uma ferramenta que permite formatar e corrigir o código PHP automaticamente, ajudando a manter padrões de codificação consistentes em projetos.

Como posso instalar o PHP CS Fixer?

Você pode instalar o PHP CS Fixer utilizando o Composer, baixando o arquivo PHAR ou utilizando Docker. Cada método oferece flexibilidade conforme suas necessidades de projeto.

Quais são as principais funcionalidades do PHP CS Fixer?

Entre as principais funcionalidades estão a correção automática de estilo de código, suporte a regras personalizadas e integração com ferramentas de CI/CD para automação de processos.

É possível personalizar as regras no PHP CS Fixer?

Sim, você pode personalizar as regras de acordo com as necessidades do seu projeto, utilizando um arquivo de configuração onde pode definir quais regras aplicar.