PHP CS Fixer: Aprenda a padronizar seu código

O PHP CS Fixer (PHP Coding Standards Fixer) é uma ferramenta de linha de comando que corrige (Fixer) arquivos PHP adequando-os para padrões de codificação (Coding Standards); Você pode formatar facilmente um arquivo PHP conforme as regras da PSR-1 e PSR-2, ou você pode adotar outros padrões de formatação utilizados pela comunidade, como o padrão adotado pelo Symfony, ou pelo Laravel, por exemplo. Além disso, você também pode definir o seu próprio estilo de formatação de código através de um arquivo de configuração.

O PHP CS Fixer é um projeto open source, hospedado no github https://github.com/FriendsOfPHP/PHP-CS-Fixer e mantido pelo pessoal da SensioLabs. As mentes brilhantes por trás desse projeto são o Fabien Potencier (Criador do Symfony Framework) e o Dariusz Rumiński.

Instalação

Existem várias maneiras de realizar a instalação da ferramenta no seu computador, para que o artigo não fique muito extenso e chato, vou abordar a instalação via Composer — julgo essa ser a mais transparente de todas, independente do seu sistema operacional.

Para as demais maneiras de instalação, consulte a documentação no site do projeto.

Utilizando o Composer temos duas opções de instalação, uma global (disponível em qualquer lugar do sistema operacional) e a outra localmente (como dependência de desenvolvimento especificada no arquivo composer.json).

Para instalar globalmente:

Execute o seguinte comando no seu terminal:

$ composer global require friendsofphp/php-cs-fixer

Em seguida, você precisa certificar se o diretório global dos binários do Composer está definido na variável de ambiente PATH do seu sistema operacional.
Por padrão, ele aponta para C:\Users\<user>\AppData\Roaming\Composer no Windows e /Users/<user>/.composer no Mac OSX. No Linux ele pode estar em $XDG_CONFIG_HOME/composer ou /home/<user>/.composer.
Você pode consultar essa seção na documentação do Composer para obter mais detalhes.

Observação:(Nessa altura do campeonato, configurar a variável de ambiente PATH acaba sendo uma atividade trivial para a maioria de nós… Por isso, não vou abordar isso nesse post. Se você tiver dificuldade nessa configuração, existem no Google centenas de tutorias específicos sobre esse assunto.)

Para instalar localmente:

Execute o seguinte comando no seu terminal:

$ composer require friendsofphp/php-cs-fixer --dev

Esse comando vai adicionar o pacote para seção require-dev do arquivo composer.json.

Atualização

Você pode atualizar a versão do PHP CS Fixer executando o comando:

$ composer global update friendsofphp/php-cs-fixer

ou

$ composer update friendsofphp/php-cs-fixer

dependendo da forma de instalação escolhida.

Utilização

O comando fix consertar os problemas de padrões de codificação em um determinado arquivo ou vários arquivos em um diretório e seus subdiretórios:

$ php-cs-fixer fix /path/arquivo.php
$ php-cs-fixer fix /path/diretorio

A opção –format é usada para formatar a saída. Os formatos suportados são txt (padrão), json, xml, checkstyle e junit.
A opção –verbose mostrará as regras aplicadas. Ao usar o formato txt, ele também exibirá notificações de progresso.
A opção –rules limita as regras a serem aplicadas no projeto:

$ php-cs-fixer fix /path/arquivo.php --rules=@PSR2

Por padrão as regras da PSR1 e PSR2 são utilizadas.

A opção –rules permite que você escolha as regras exatas a serem aplicadas (os nomes das regras devem ser separados por uma vírgula):

$ php-cs-fixer fix /path/arquivo.php --rules=line_ending,full_opening_tag

Você também pode listar as regras que você não deseja, colocando “-” na frente do nome da regra, se isso for mais conveniente, exemplo -nome_da_regra:

$ php-cs-fixer fix /path/arquivo.php --rules=-line_ending,-full_opening_tag

Com isso você pode usar combinações de regras, como mostrado no exemplo abaixo, onde o padrão @symfony está sendo aplicando, porém sem uma linha extra no final de cada arquivo (-line_ending) :

$ php-cs-fixer fix /path/arquivo.php --rules=@Symfony,-line_ending

A configuração completa das regras pode ser fornecida usando uma string com formato json.

$ php-cs-fixer fix /path/arquivo.php --rules='{"concat_space": {"spacing": "one"}}'

Para facilitar o entendimento, vou listar abaixo uma pequena lista de regras, com uma breve descrição.

• ‘concat_space’ => [‘spacing’ => ‘one’] — A concatenação deve ser usada com pelo menos um espaço em branco.
• ‘no_unused_imports‘ — Declarações de import (use) não utilizadas devem ser removidas.
• ‘blank_line_after_namespace‘ — Deve existir uma linha em branco após a declaração de namespace.
• ‘blank_line_before_return‘ — Uma linha em branco deve preceder uma declaração de return
• ‘blank_line_after_opening_tag‘ — Certifica que não existe nenhum código junto a tag de abertura do PHP e garanti que seja pulada uma linha após essa tag.

A ferramenta possui alguns regras que são consideradas de “risco” (Risky rules) . As Risky rules são regras que mudam o comportamento do código. Por padrão, essas regras só são executadas se você habilitar a opção –allow-risky=true .

Abaixo segue exemplos de algumas regras de risco:

• dir_constant — Substitui a expressão dirname(__FILE__) pela constante __DIR__
• is_null — Substitui a função is_null($var) pela expressão null === $var.

Para conhecer todas as outras regras disponíveis, verifique a lista completa no site do projeto http://cs.sensiolabs.org/ .

Fora isso, ainda temos outras opções interessantes:

A opção –dry-run executará o fix sem fazer alterações em seus arquivos.

A opção –diff pode ser usado para exibir todas as mudanças que o fix faz.

Configuração do PHP CS Fixer

Obviamente não vamos ficar repetindo as regras a cada utilização, em vez de usar opções de linha de comando para personalizar as regras, podemos criar um arquivo de configuração e centralizar todas elas nesse arquivo. Você pode salvar tudo em um arquivo com o nome .php_cs.dist no diretório raiz do seu projeto. O arquivo deve retornar uma instância do PhpCsFixer\ConfigInterface que permite configurar as regras, os arquivos e os diretórios que precisam ser analisados.

Você também pode criar o arquivo .php_cs, que é a configuração local que será usada em vez da configuração do projeto.

No exemplo abaixo — retirado da documentação — iremos adicionar duas regras à lista padrão de configuração da PSR2.

Não entendeu o arquivo acima? calma, eu te explico:

• Linha 3 — Estamos criando o “Finder”, essa é a classe responsável por percorrer e procurar os arquivos que serão analisados.
• Linha 4 — Com o método exclude() você pode informar para o Finder quais diretórios ele deve ignorar. ( Funciona só com diretórios, você pode chamar esse método várias vezes pra ignorar vários diretórios se for preciso. )
• Linha 5 — O método notPath() tem o funcionamento semelhante ao exclude() porém funciona somente com arquivos.
• Linha 6 — Informamos o diretório que será feita a analise. (a constante __DIR__ retorna o diretório onde o arquivo esta inserido )
• Linha 8 -Nessa linha chamamos a classe responsável por receber as regras de configuração e aplica-las nos arquivos.
• Linha 9 a 13 — Aqui estamos definindo as regras que serão aplicadas.
• Linha 14 — Informamos para classe de configuração onde ela deve procurar os arquivos, baseado na parametrização da classe Finder.

No meu Gist ( clique aqui ) você encontra um arquivo .php_cs.dist bem completo com as regras de padronização utilizadas no framework Laravel, esse arquivo foi construído usando a predefinição Laravel do StyleCI .

Cache

O mecanismo de cache é habilitado por padrão. Isso acelerará as execuções corrigindo apenas arquivos que foram modificados desde a última vez. A ferramenta irá corrigir todos os arquivos se a versão do PHP CS Fixer tiver mudado ou a lista de regras tiver sofrido alterações. O cache é suportado apenas para a ferramenta baixada como arquivo phar ou instalada via composer.

Caso queira, você pode desabilitar o cache usando a opção –using-cache=no ou pelo arquivo de configuração:

<?php
return PhpCsFixer\Config::create()->setUsingCache(false);

Dicas para utilização em projetos

Eu utilizo bastante o PHP CS Fixer como dependência de desenvolvimento nos meus projetos, pra facilitar minha vida eu crio scripts customizados do Composer para executarem o php-cs-fixer no meu código. Como eu sou um cara que adora compartilhar conhecimento, vou aproveitar esse artigo pra dar essas “Dicas”!

Vamos lá! o primeiro passo é acessar o diretório do seu projeto PHP e instalar o php-cs-fixer como dependência de desenvolvimento, você pode fazer isso pelo terminal:

$ composer require friendsofphp/php-cs-fixer --dev

Com a ferramenta instalada, agora vamos criar dois scripts no composer, pra isso edite o arquivo composer.json da seguinte forma:

"require-dev": {
    "friendsofphp/php-cs-fixer": "^2.10"
},
"scripts": {
    "check-style": "php-cs-fixer fix --diff --verbose --dry-run .",
    "fix-style": "php-cs-fixer fix ."
}

• check-style: A ideia desse comando é utilizar as opções –diff e –dry-run juntas para visualizar todas alterações que o fix irá fazer no código sem que elas sejam feitas de fato.
• fix-style: Esse comando aplica as regras de padronização no código do seu projeto.

Agora, no terminal basta executar os scripts :

composer fix-style
//ou
composer check-style

Agora que eu já te mostrei o “caminho das pedras”, utilize o PHP CS Fixer e deixe seu código mais organizado!

P.S: ( Esse artigo também está publicado em https://blog.especializati.com.br/aprenda-como-utilizar-o-php-cs-fixer-e-padronize-seu-codigo )