Dicas para criar sua primeira regra Rector para transformar o código PHP

Rector é uma ferramenta reconstrutora para PHP. Ele pega o código-fonte e as regras de transformação como entradas e modifica o código de acordo com as regras como saída.

Mesmo que não pensemos nisso, costumamos usar ferramentas para transformar o código PHP. Por exemplo, PHP CodeSniffer pode validar se o código obedece aos padrões PSR e, quando não , executando o comando phpcbf pode corrigi-lo automaticamente. Ou PHP-Scoper definirá o escopo das dependências no projeto para evitar possíveis conflitos.

O Rector é diferente dessas ferramentas por ser um meta-aplicativo. Não tem um objetivo predeterminado, como fixar estilos ou definir o escopo do projeto. Em vez disso, ele transformará o código seguindo as regras, para quaisquer que sejam as regras fornecidas. Então, Rector pode reproduzir perfeitamente PHP CodeSniffer, PHP-Scoper ou qualquer outra ferramenta de transformação de código.

Neste artigo, compartilharei algumas dicas para criar regras no Rector.

Os pilares do reitor

Rector está sobre os ombros de dois gigantes:

• PHP Parser : uma biblioteca que analisa o código PHP, permitindo a análise e manipulação de código estático
• PHPStan : uma ferramenta de análise estática

Graças ao PHP Parser, Rector pode manipular o código usando nós em um AST (abreviação de Abstract Syntax Tree ). E graças ao PHPStan, Rector pode entender o código, portanto, é capaz de mapear, navegar e validar os relacionamentos entre as entidades no código, como obter o ancestral de uma classe ou todas as suas interfaces implementadas.

É uma boa ideia ter um conhecimento básico dessas duas bibliotecas antes de começar com o Rector e continuar aprendendo com sua documentação enquanto trabalhamos com o Rector. Na verdade, quanto mais complexa for a regra do Reitor, mais importante se torna ter um bom domínio dessas duas bibliotecas.

Quais são as regras do reitor?

Uma regra é uma classe PHP herdada de AbstractRector , que executa as transformações nos nós do AST (correspondente ao arquivo PHP analisado).

É composto de três métodos principais, que devemos satisfazer:

• getRuleDefinition : usado para documentar a regra
• getNodeTypes : em que tipo de nó a regra será aplicada
• refactor : lógica para produzir o novo nó AST

Por exemplo, a regra DowngradeNullCoalescingOperatorRector substitui o operador ??= introduzido no PHP 7.4 por seu equivalente no PHP 7.3. Ele tem esta implementação: >

 use PhpParser \ Node;
use PhpParser \ Node \ Expr \ Assign;
use PhpParser \ Node \ Expr \ AssignOp \ Coalesce como AssignCoalesce;
use PhpParser \ Node \ Expr \ BinaryOp \ Coalesce;
use Rector \ Core \ Rector \ AbstractRector;
use Symplify \ RuleDocGenerator \ ValueObject \ CodeSample \ CodeSample;
use Symplify \ RuleDocGenerator \ ValueObject \ RuleDefinition; classe final DowngradeNullCoalescingOperatorRector estende AbstractRector
{ public function getRuleDefinition (): RuleDefinition { return new RuleDefinition ('Remover operador de coalescência nulo ??=', [ new CodeSample ( <<<'CODE_SAMPLE'
$ array=[];
$ array ['user_id'] ??='valor';
CODE_SAMPLE , <<<'CODE_SAMPLE'
$ array=[];
$ array ['user_id']=$ array ['user_id'] ??'valor';
CODE_SAMPLE ), ]); } /** * @return string [] */ public function getNodeTypes (): array { return [AssignCoalesce:: class]; } /** * @param AssignCoalesce $ node */ refator de função pública (Node $ node):? Node { retornar new Assign ($ node-> var, new Coalesce ($ node-> var, $ node-> expr)); }
} 

Devemos fornecer um exemplo do código antes e depois da transformação. O Rector então usa esses dois estados para documentar as mudanças, usando o formato diff, como feito aqui :

 $ array=[];
-$ array ['user_id'] ??='valor'; 
 + $ array ['user_id']=$ array ['user_id'] ??'valor'; 

getNodeTypes

Nesta função, indicamos em qual nó da AST a transformação será aplicada. Esses nós vêm diretamente do PHP Parser .

No exemplo acima, a regra é aplicada apenas em nós do tipo Coalesce (apelidado de AssignCoalesce ), que é o nó que representa ??=.

Alguns exemplos de outros nós são:

• FuncCall : sempre que chamar uma função, como var_dump("hello")
• MethodCall : sempre que chamar um método de uma classe, como $foo->bar()
• Atribuir : ao atribuir um valor via =
• Equal , NotEqual , Identical e NotIdentical : sempre que usar o operador binário ==, !=, === ou !==, respectivamente

refactor

Esta função realiza a transformação, se necessário. Possui tipo de retorno ? Node , o que significa:

• Retorne um novo nó, que substituirá o nó antigo; ou
• Retorne null , para significar nenhuma mudança

Observe que retornar null significa “não modifique o nó”; não significa “remover o nó”.

A regra acima visa substituir $ foo ??=$ bar por seu equivalente $ foo=$ foo ?? $ bar . A função refactor então retorna este novo nó:

 return new Assign ( $ node-> var, novo Coalesce ( $ node-> var, $ node-> expr )
); 

O novo nó é do tipo Atribuir , que é o = em $ foo=$ foo ?? $ bar . Este tipo requer dois elementos:

• A variável $ foo , que é recuperada do nó original, como $node->var
• A expressão $ foo ?? $ bar

Para criar a expressão, aninhamos um novo nó nela, do tipo [Coalesce] ( https://github.com/nikic/PHP-Parser/blob/master/lib/PhpParser/Node/Expr/BinaryOp/Coalesce.php ) , que é o ?? em $ foo ?? $ bar . O operador de coalescência requer dois elementos:

• A expressão à esquerda $ foo , que é recuperada do nó original como $node->var
• A expressão à direita $ bar , que é recuperada do nó original como $node->expr

Este exemplo mostra o conceito básico do que envolve a criação de uma regra:

• Descubra qual novo nó satisfaz o código-alvo
• Identifique os dados de que necessita
• Dados de porta (variáveis, expressões) do nó antigo para o novo nó

Reutilizando código de regras existentes

No momento em que este artigo foi escrito, o repo Rector fornece quase 700 regras , envolvendo transformações de muitos tipos. Essas regras existentes são uma fonte maravilhosa para nos ajudar a implementar nossas próprias regras personalizadas.

Portanto, este é o meu conselho: sempre que precisar criar uma regra personalizada, verifique primeiro se uma lógica semelhante já foi codificada em alguma das regras existentes. Provavelmente, haverá.

Por exemplo, implementei a regra -strip_tags ($ string, ['a','p']); + strip_tags ($ string,'<'. implode ('> <', ['a','p']).'>');

Agora, podemos não saber o tipo do parâmetro durante a análise estática. Por exemplo, esta função retorna uma string ou uma matriz:

 function getStringOrArray () { if (rand (0, 1)) { return ['a','p']; } return'ap';
}

 -strip_tags ($ string, getStringOrArray ()); 
 + strip_tags ($ string, is_array (getStringOrArray ())? ('<'. implode ('> <', getStringOrArray ()).'>'): getStringOrArray ()); 

 -strip_tags ($ string, getStringOrArray ()); 
 + $ var=getStringOrArray ();
+ strip_tags ($ string, is_array ($ var)? ('<'. implode ('> <', $ var).'>'): $ var); 

 $ var="blá, blá, blá";
-strip_tags ($ string, getStringOrArray ()); 
 + $ var=getStringOrArray ();
+ strip_tags ($ string, is_array ($ var)? ('<'. implode ('> <', $ var).'>'): $ var);  var_dump ($ var);
//Ele espera"blá, blá, blá". Obteve"ap"

 classe SomeClass { execução de função pública ($ items) {
-para ($ i=5; $ i <=count ($ items); $ i ++) {
 + $ itemsCount=count ($ items);
+ para ($ i=5; $ i <=$ itemsCount; $ i ++) { echo $ items [$ i]; } } }

 $ variableName=$ this-> variableNaming-> resolveFromFuncCallFirstArgumentWithSuffix ( $ node, 'Contar', 'itemsCount', $ forScope
);

 vendor/bin/phpunit rules/solid/tests/Rector/Class_/FinalizeClassesWithoutChildrenRector/FinalizeClassesWithoutChildrenRectorTest.php 

 Houve 1 falha: 1) Rector \ DowngradePhp73 \ Tests \ Rector \ List_ \ DowngradeListReferenceAssignmentRector \ DowngradeListReferenceAssignmentRectorTest:: teste com conjunto de dados # 4 (objeto Symplify \ SmartFileSystem \ SmartFileInfo (...))
rules/downgrade-php73/tests/Rector/List_/DowngradeListReferenceAssignmentRector/Fixture/nested_list.php.inc
Falha ao afirmar que a string corresponde à descrição do formato. 

 vendor/bin/phpunit rules/solid/tests/Rector/Class_/FinalizeClassesWithoutChildrenRector/FinalizeClassesWithoutChildrenRectorTest.php--filter=test # 4 

 dump ($ this-> print ($ node));
morrer;