Rector Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel-Specific Optimization: The package is purpose-built for Laravel, addressing version upgrades (e.g., Laravel 12→13), deprecated patterns (e.g., Facade aliases, legacy factories), and modern best practices (e.g., type declarations, DI over static calls). This aligns perfectly with Laravel’s evolving ecosystem and reduces manual refactoring effort.
  • Modular Rule Sets: Rules are organized into granular sets (e.g., LARAVEL_CODE_QUALITY, LARAVEL_COLLECTION, LARAVEL_STATIC_TO_INJECTION), allowing targeted application (e.g., only upgrade Eloquent queries without touching Facades).
  • Composer-Based Auto-Detection: Leverages composer.json to auto-select rules for the current Laravel version, reducing configuration overhead for version upgrades.
  • Opinionated + Configurable Rules: Offers both pre-packaged rules (e.g., LARAVEL_TYPE_DECLARATIONS) and customizable ones (e.g., RouteActionCallableRector), balancing convenience and flexibility.

• Gaps:

  • No Direct Database/ORM Schema Migrations: Focuses on PHP code, not database schema changes (e.g., renaming columns in users table for Laravel Auth). Requires manual or separate tooling (e.g., Laravel Migrations, Doctrine DBAL).
  • Limited Support for Custom Packages: While it includes rules for Laravel Cashier/Livewire, third-party packages (e.g., Spatie, Laravel Nova) may lack coverage. Requires community contributions or custom rules.
  • No Backward Compatibility Guarantees: Rules are designed for forward migration (e.g., Laravel 10→11), not reverting changes. May conflict with partial upgrades.

Integration Feasibility

• Low-Coupling Design:
  • Dev Dependency: Installed as --dev, ensuring it doesn’t affect production builds.
  • Isolated Execution: Runs as a standalone CLI tool (rector process src) or CI step, with no runtime overhead.
  • No Core Laravel Overrides: Modifies code via static analysis (AST), not runtime hooks, avoiding conflicts with existing plugins or custom logic.
• CI/CD Integration:
  • Ideal for pre-merge checks (e.g., GitHub Actions) to enforce code quality before production.
  • Can be gated in PRs to block deprecated patterns (e.g., Facade aliases) via custom GitHub Actions or PHPStan rules.
• IDE Compatibility:
  • Rules like LARAVEL_TYPE_DECLARATIONS improve IDE autocompletion and static analysis (e.g., PHPStan, Psalm), but may require IDE resyncing post-rector.

Technical Risk

• False Positives/Negatives:
  • Risk: Some rules (e.g., RemoveDumpDataDeadCodeRector) may aggressively remove debug code or misinterpret dynamic method calls (e.g., $model->{$method}()).
  • Mitigation: Run in dry mode (rector process --dry-run) and review diffs. Use --skip to exclude problematic files/directories.
• Breaking Changes:
  • Risk: Rules like LARAVEL_STATIC_TO_INJECTION or LARAVEL_ELOQUENT_MAGIC_METHOD_TO_QUERY_BUILDER may break existing logic if not thoroughly tested.
  • Mitigation: Test in a staging environment or Docker container mirroring production. Use feature flags or branch-specific configs to roll out incrementally.
• Performance Impact:
  • Risk: Large codebases may experience slow processing during initial runs (Rector analyzes the entire AST).
  • Mitigation: Run during off-peak hours or in CI. Cache results with --cache-dir for repeated runs.
• Dependency Conflicts:
  • Risk: Conflicts with other Rector packages (e.g., rector/rector) or PHP versions (<8.1).
  • Mitigation: Pin versions in composer.json and test in isolated environments.

Key Questions for Stakeholders

1. Upgrade Strategy:
   • Are we upgrading Laravel versions incrementally (e.g., 10→11→12) or skipping versions (e.g., 10→13)? This affects rule set selection.
   • Do we need to support legacy codebases (e.g., Laravel 5.8) or focus on modern stacks (Laravel 10+)?
2. Code Quality vs. Breaking Changes:
   • Should we prioritize non-breaking rules (e.g., LARAVEL_CODE_QUALITY) first, or accept breaking changes for long-term benefits (e.g., LARAVEL_STATIC_TO_INJECTION)?
3. Testing Coverage:
   • What’s our test coverage threshold for post-rector code? (e.g., 90% unit tests + critical path E2E tests).
   • Can we auto-generate tests for rectored code (e.g., using Pest or Laravel’s testing tools)?
4. Rollback Plan:
   • How will we revert if a rule introduces bugs? (e.g., Git bisect, backup branches, or manual diff reverts).
5. Team Adoption:
   • Does the team have experience with Rector, or will training be needed?
   • Will developers need to adjust to new patterns (e.g., DI over Facades)?

Integration Approach

Stack Fit

• Primary Use Cases:
  • Laravel Version Upgrades: Automate breaking changes (e.g., Laravel 12→13) without manual refactoring.
  • Code Modernization: Replace deprecated patterns (e.g., Facade aliases, abort() helpers) with modern equivalents.
  • Type Safety: Add PHPDoc types or return type hints to improve IDE support and static analysis.
  • CI/CD Enforcement: Block PRs with deprecated code via GitHub Actions or custom scripts.
• Compatibility:
  • Laravel Versions: Supports Laravel 5.8+ (with version-specific rule sets). Tested up to Laravel 13 (as of last release).
  • PHP Versions: Requires PHP 8.1+ (due to Rector’s dependencies). Avoid PHP 7.x.
  • Tooling:
    • IDE: Works with PHPStorm, VSCode (with Intelephense), and any IDE supporting PHPStan/Psalm.
    • Static Analysis: Integrates with PHPStan/Psalm for post-rector validation.
    • Testing: Compatible with Pest, PHPUnit, and Laravel’s testing tools.

Migration Path

1. Assessment Phase:
   • Run rector process --dry-run on a staging environment to identify affected files/rules.
   • Analyze the diff for high-risk changes (e.g., Facade replacements, Eloquent query updates).
2. Incremental Rollout:
   • Phase 1: Apply non-breaking rules (e.g., LARAVEL_CODE_QUALITY, LARAVEL_TYPE_DECLARATIONS).
   • Phase 2: Test breaking rules (e.g., LARAVEL_STATIC_TO_INJECTION) in a feature branch.
   • Phase 3: Integrate into CI/CD for pre-merge validation.
3. Configuration:
   • Start with composer-based auto-detection for version upgrades:

     return RectorConfig::configure()
         ->withSetProviders(LaravelSetProvider::class)
         ->withComposerBased(laravel: true);
     

   • Gradually add manual sets for custom rules (e.g., LARAVEL_COLLECTION for performance optimizations).
4. Post-Migration:
   • Update tests to reflect changes (e.g., new method signatures, DI patterns).
   • Re-run static analysis (PHPStan/Psalm) to catch edge cases.

Compatibility Considerations

• Avoid Conflicts:
  • Exclude vendor directories (--exclude vendor/) and generated files (e.g., bootstrap/cache/).
  • Skip files with custom logic (e.g., --skip src/Custom/Logic.php).
• Custom Rules:
  • Extend the package with custom rules using composer make:rule for project-specific needs (e.g., legacy API wrappers).
• Third-Party Packages:
  • Test thoroughly with packages like Laravel Nova, Forge, or custom plugins, as they may rely on deprecated patterns.

Sequencing

1. Pre-Upgrade:
   • Run Rector before upgrading Laravel to apply version-specific rules (e.g., Laravel 12→13).
2. Post-Upgrade:
   • Use Rector to clean up deprecated code introduced by the new Laravel version.
3. Ongoing:
   • Schedule periodic runs (e.g., quarterly) to apply new rules as Laravel evolves.
   • Integrate into release cycles (e.g., run before major feature freezes).

Operational Impact

Maintenance

• Pros:
  • Reduced Technical Debt: Automates repetitive refactoring (e.g., Facade updates, type hints).