GUÍA COMPLETA DE RECTOR PHP: INSTALACIÓN, CONFIGURACIÓN Y REFACTORIZACIÓN AUTOMÁTICA DE CÓDIGO

Rector es una herramienta de código abierto que permite actualizar y refactorizar automáticamente código PHP. Analiza el código mediante un Árbol de Sintaxis Abstracta, o AST, con PHP-Parser y aplica reglas de transformación inteligentes.
Rector se ha convertido en el estándar de la comunidad PHP para:
  • Actualizar de PHP 5.3 a PHP 8.5, y versiones posteriores.
  • Migrar frameworks y librerías, como Symfony, Laravel, Doctrine, PHPUnit, etc..
  • Mejorar la calidad del código, como añadir tipado, eliminar código muerto, aplicar buenas prácticas.
  • Mantener la base de código actualizada de forma continua en CI/CD.
A diferencia de un formateador, como PHP-CS-Fixer, Rector modifica el código de forma semántica y segura.

¿Por qué usar Rector?

  • Gran ahorro de tiempo: Lo que antes tomaba semanas de refactorización manual se reduce a minutos u horas.
  • Actualizaciones sencillas: Pasar de PHP 7.4 a 8.4 o de Laravel 10 a 12 se vuelve mucho más simple.
  • Calidad de código constante: Se puede integrar en CI para que cada pull request mejore automáticamente el código.
  • Más de 600 reglas listas para usar y paquetes oficiales y de la comunidad.

Instalación de Rector

Requiere PHP 7.2 o superior. Se instala como dependencia de desarrollo:

composer require rector/rector --dev
Después generar el archivo de configuración:

vendor/bin/rector
Esto crea "rector.php" en la raíz del proyecto.

Configuración básica (rector.php)

La configuración moderna usa "RectorConfig::configure()":

declare(strict_types=1);

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
        __DIR__ . '/tests',
        __DIR__ . '/app', // para Laravel
    ])
    // Sets preparados (recomendado)
    ->withPreparedSets(
        deadCode: true,
        codeQuality: true,
        codingStyle: true,
        typeDeclarations: true,
        privatization: true,
        naming: true,
        earlyReturn: true
    )
    // O sets de PHP específicos
    ->withPhpSets(php84: true)
    // Sets basados en Composer (ideal para frameworks)
    ->withComposerBased(
        phpunit: true,
        symfony: true,
        doctrine: true,
        laravel: true // requiere rector-laravel
    );

Cómo ejecutar Rector

Recomendación de hacer vista previa

vendor/bin/rector process --dry-run

Aplicar cambios

vendor/bin/rector process

Opciones útiles

  • "--dry-run": Solo muestra el diff.
  • "--max-changes=50": Limita la cantidad de cambios por ejecución (muy útil en proyectos grandes).
  • "validate-config": Valida la configuración sin procesar archivos (añadido en versiones recientes).

Niveles. La forma más segura de empezar

En lugar de aplicar todos los sets de golpe, es mejor usar niveles progresivos:

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src'])
    ->withTypeCoverageLevel(0)   // Empieza en 0 y sube de 1 en 1
    ->withDeadCodeLevel(0)
    ->withCodeQualityLevel(0);
Cada vez que se sube un nivel, Rector aplica un conjunto más avanzado de reglas. Esto genera pull requests pequeños y fáciles de revisar.

Integración con Laravel

Instalar el paquete de la comunidad:

composer require driftingly/rector-laravel --dev
Después activar los sets de Laravel en "rector.php". Se puede automatizar migraciones de versiones, convertir helpers, mejorar Collections, eliminar magic methods, etc.

Mejores prácticas

  • Ejecutar primero con ""--dry-run" y revisar el diff.
  • Tener una buena cobertura de tests antes de aplicar cambios grandes.
  • Combinarlo con PHPStan y PHP-CS-Fixer / Laravel Pint.
  • Integrar en CI, como GitHub Actions, GitLab CI, etc., para que se ejecute automáticamente.
  • Empezar conun directorio o un nivel a la vez.
  • Usar "withSkip()" para excluir reglas o archivos problemáticos.