Rector PHP: guia completo com exemplos práticos

Rector é uma ferramenta poderosa para refatoração automática de código PHP. Trata-se de uma biblioteca que analisa seu código usando uma árvore sintática abstrata (AST) e aplica regras de transformação predefinidas. Isso permite automatizar tarefas rotineiras de atualização de código, como migrar para novas versões do PHP, adotar novos recursos da linguagem, corrigir construções obsoletas e melhorar a qualidade geral do código.

Por que usar o Rector? No desenvolvimento PHP moderno, os projetos crescem rapidamente e mantê-los atualizados se torna cada vez mais complexo. Refatorar manualmente milhares de linhas de código é um processo demorado e sujeito a erros. O Rector resolve esse problema permitindo realizar transformações complexas em segundos. Ele é especialmente útil ao atualizar do PHP 7.x para o 8.x, ao migrar de frameworks legados (como Zend Framework 1 para Laminas) ou ao implementar tipos estritos e padrões modernos.

O Rector funciona com base no conceito de "conjunto de regras". Você define quais transformações devem ser aplicadas (por exemplo, "substituir todas as chamadas de funções array_* por str_*"), e o Rector encontra todos os locais relevantes no código e faz as alterações. A ferramenta é totalmente personalizável: você pode usar conjuntos de regras prontos da comunidade ou criar os seus próprios. O Rector se integra a pipelines de CI/CD, permitindo verificar e corrigir o código automaticamente a cada commit.

Instalação

O Rector é instalado via Composer, o gerenciador de pacotes padrão do PHP. Execute o seguinte comando na raiz do seu projeto:

composer require rector/rector --dev

A flag --dev indica que o pacote será instalado apenas para desenvolvimento, uma boa prática, já que o Rector não é necessário no ambiente de produção.

Após a instalação, verifique se tudo está funcionando:

vendor/bin/rector --version

Se você preferir uma instalação global (não recomendada para projetos), execute:

composer global require rector/rector

O Rector requer PHP 7.2 ou superior. Recomenda-se usar PHP 8.0+ para obter o máximo de desempenho e suporte a todos os recursos.

Início rápido: exemplo mínimo funcional

Vamos criar um arquivo PHP simples que precisa ser refatorado. Suponha que temos um código legado usando create_function(), que foi removido no PHP 8.0.

Passo 1. Crie o arquivo exemplo.php:

<?php

$funcaoAntiga = create_function('$a, $b', 'return $a + $b;');
echo $funcaoAntiga(1, 2); // Exibe 3

Passo 2. Crie o arquivo de configuração rector.php na raiz do projeto:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Php80\Rector\Function_\CreateFunctionToAnonymousFunctionRector;

return static function (RectorConfig $rectorConfig): void {
    // Define quais diretórios analisar
    $rectorConfig->paths([
        __DIR__ . '/exemplo.php',
    ]);

    // Registra a regra para substituir create_function por funções anônimas
    $rectorConfig->rule(CreateFunctionToAnonymousFunctionRector::class);
};

Passo 3. Execute o Rector:

vendor/bin/rector process --dry-run

A flag --dry-run mostra quais alterações serão feitas, mas não as aplica. Para modificar os arquivos de fato, execute:

vendor/bin/rector process

Resultado: O arquivo exemplo.php será transformado em:

<?php

$funcaoAntiga = function ($a, $b) {
    return $a +