Rector para PHP: guía completa con ejemplos prácticos

Rector es una potente herramienta para el refactorizado automático de código PHP. Se trata de una librería que analiza tu código mediante un árbol de sintaxis abstracta (AST) y aplica reglas de transformación predefinidas. Esto permite automatizar tareas rutinarias de actualización de código, como migrar a nuevas versiones de PHP, implementar nuevas características del lenguaje, corregir construcciones obsoletas y mejorar la calidad general del código.

¿Para qué sirve Rector? En el desarrollo moderno con PHP, los proyectos crecen rápidamente y mantenerlos actualizados se vuelve cada vez más complejo. Refactorizar manualmente miles de líneas de código es un proceso tedioso y propenso a errores. Rector resuelve este problema permitiendo realizar transformaciones complejas en segundos. Es especialmente útil al actualizar de PHP 7.x a 8.x, al migrar desde frameworks obsoletos (por ejemplo, de Zend Framework 1 a Laminas), o al implementar tipos estrictos y patrones modernos.

Rector funciona bajo el principio de "conjunto de reglas". Tú defines qué transformaciones deseas aplicar (por ejemplo, "reemplazar todas las llamadas a funciones array_* por str_*"), y Rector encuentra todos los lugares adecuados en el código y realiza los cambios. La herramienta es totalmente personalizable: puedes usar conjuntos de reglas predefinidos por la comunidad o crear los tuyos propios. Rector se integra en pipelines de CI/CD, lo que permite verificar y corregir el código automáticamente en cada commit.

Instalación

Rector se instala a través de Composer, el gestor de paquetes estándar para PHP. Ejecuta el siguiente comando en la raíz de tu proyecto:

composer require rector/rector --dev

La bandera --dev indica que el paquete se instalará solo para desarrollo, lo cual es una buena práctica, ya que Rector no es necesario en el entorno de producción.

Después de la instalación, verifica que todo funcione correctamente:

vendor/bin/rector --version

Si prefieres una instalación global (no recomendada para proyectos), puedes ejecutar:

composer global require rector/rector

Rector requiere PHP 7.2 o superior. Se recomienda usar PHP 8.0+ para obtener el máximo rendimiento y soporte de todas las funcionalidades.

Inicio rápido: ejemplo mínimo funcional

Vamos a crear un archivo PHP simple que necesita ser refactorizado. Supongamos que tenemos código antiguo que usa create_function(), una función eliminada en PHP 8.0.

Paso 1. Crea el archivo ejemplo.php:

<?php

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

Paso 2. Crea el archivo de configuración rector.php en la raíz del proyecto:

<?php

declare(strict_types=1);

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

return static function (RectorConfig $rectorConfig): void {
    // Indicamos qué directorios analizar
    $rectorConfig->paths([
        __DIR__ . '/ejemplo.php',
    ]);

    // Registramos la regla para reemplazar create_function por funciones anónimas
    $rectorConfig->rule(CreateFunctionToAnonymousFunctionRector::class);
};

Paso 3. Ejecuta Rector:

vendor/bin/rector process --dry-run

La bandera --dry-run muestra los cambios que se realizarán sin aplicarlos. Para modificar los archivos realmente, ejecuta:

vendor/bin/rector process

Resultado: El archivo ejemplo.php se transformará en:

<?php

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