Blog EspecializaTi
João Roberto Por: João Roberto Comentar

Aprenda como utilizar o PHP CS Fixer e padronize seu código

como utilizar o PHP CS Fixer

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).

Global

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.)

Local

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 [email protected]

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 [email protected],-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.

<?php

$finder = PhpCsFixer\Finder::create()
 ->exclude('somedir')
 ->notPath('src/Symfony/Component/Translation/Tests/fixtures/resources.php')
 ->in(__DIR__);

return PhpCsFixer\Config::create()
 ->setRules([
 '@PSR2' => true,
 'strict_param' => true,
 'array_syntax' => ['syntax' => 'short'],
 ])
 ->setFinder($finder);

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

ou você pode instalar manualmente editando o arquivo composer.json do seu projeto e adicionar a dependência na seção require-dev:

"require-dev": {
    "friendsofphp/php-cs-fixer": "^2.10"
},

Se fizer a instalação manual, não esqueça de rodar composer update para que as dependências sejam de fato baixadas.

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

Utilize o PHP CS Fixer e deixe seu código mais organizado!

João Roberto

Sobre o Autor:

João Roberto

João Roberto é graduado em Sistemas para Internet, Analista de Sistemas, instrutor de algumas aulas do Portal Especializa TI e amante da tecnologia. Atua há cerca de 10 anos no mercado de T.I. efetuando trabalhos nas áreas de redes, infraestrutura e desenvolvimento. Nas horas vagas procura compartilhar conhecimento interagindo nas comunidades ou escrevendo artigos em seu blog pessoal. ( http://medium.com/@joaorobertopb ) Atualmente trabalha como Analista de Sistemas na Mitsubishi Motors Brasil.

Todos os direitos reservados © 2018 - EspecializaTi. É proibida a reprodução total ou parcial deste conteúdo.