Rector Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Specific Transformation: The package is a specialized extension of Rector, a PHP refactoring tool, tailored for Laravel. It aligns perfectly with Laravel’s ecosystem by providing version-specific upgrade rules (e.g., Laravel 12→13) and opinionated refactorings (e.g., facades to DI, legacy factories to classes).
• Modular Design: Rules are organized into sets (e.g., LaravelSetList::LARAVEL_CODE_QUALITY, LaravelLevelSetList::UP_TO_LARAVEL_130), allowing granular adoption. This modularity enables incremental migration (e.g., apply only Eloquent magic method refactors first).
• Composer-Based Auto-Detection: Leverages composer.json to auto-select rules based on current Laravel version, reducing manual configuration overhead.
• Integration with Rector’s Core: Built on Rector’s rule engine, ensuring compatibility with existing Rector workflows (e.g., parallel processing, dry runs, caching).

Integration Feasibility

• Low Friction: Requires only a dev dependency (composer require --dev driftingly/rector-laravel) and minimal config (e.g., LaravelSetProvider or manual set selection).
• CI/CD Friendly: Designed for automated pipelines (e.g., GitHub Actions workflows for testing refactors pre-merge).
• IDE Support: Rules like LARAVEL_FACTORIES improve IDE autocompletion, while LARAVEL_TYPE_DECLARATIONS enhances static analysis (e.g., PHPStan).
• Backward Compatibility: Rules are version-aware (e.g., UP_TO_LARAVEL_130 includes all prior sets), enabling safe upgrades.

Technical Risk

• Rule Overlap: Some refactors (e.g., LARAVEL_STATIC_TO_INJECTION) may conflict with existing DI patterns. Mitigation: Run in dry mode (--dry-run) first.
• False Positives: Opinionated rules (e.g., RemoveDumpDataDeadCodeRector) may remove legitimate debug code. Mitigation: Exclude files/directories via Rector’s --exclude-paths.
• Performance: Large codebases may slow down during refactoring. Mitigation: Use Rector’s parallel processing (--parallel) and cache (--cache).
• Custom Logic: Some rules (e.g., RouteActionCallableRector) require manual configuration. Mitigation: Document edge cases in the Rector config.

Key Questions

1. Upgrade Strategy:
   • Should we apply all version-specific rules at once (e.g., UP_TO_LARAVEL_130) or incrementally (e.g., one major version per release)?
2. Opinionated Rules:
   • Which opinionated sets (e.g., LARAVEL_CODE_QUALITY, LARAVEL_STATIC_TO_INJECTION) align with our team’s coding standards?
3. Testing:
   • How will we verify refactored code? (e.g., regression tests, manual review of critical paths).
4. Dependency Management:
   • Will this package conflict with other Rector extensions (e.g., rector/rector) or custom rules?
5. Rollback Plan:
   • How will we revert if a refactor introduces bugs? (e.g., Git bisect, backup branches).

Integration Approach

Stack Fit

• Laravel Monorepo/Repo: Ideal for legacy codebases or projects migrating between Laravel versions (e.g., 8→10→13).
• PHP Version: Requires PHP 8.1+ (per Rector’s baseline), but rules are backward-compatible with older Laravel versions.
• Toolchain Compatibility:
  • CI/CD: Integrates with GitHub Actions, GitLab CI, or Jenkins via Rector’s CLI.
  • IDE: Works with PHPStorm, VSCode (via Intelephense) for improved autocompletion after refactoring.
  • Static Analysis: Complements tools like PHPStan, Psalm, or Pint for code quality.
• Custom Rules: Extendable via Rector’s composer make:rule for project-specific refactors.

Migration Path

1. Assessment Phase:
   • Run rector process in dry mode (--dry-run) to preview changes.
   • Analyze rule coverage using LaravelSetProvider vs. manual sets.
2. Incremental Rollout:
   • Phase 1: Apply non-breaking rules (e.g., LARAVEL_COLLECTION, LARAVEL_TYPE_DECLARATIONS).
   • Phase 2: Tackle version-specific upgrades (e.g., UP_TO_LARAVEL_130).
   • Phase 3: Adopt opinionated refactors (e.g., LARAVEL_STATIC_TO_INJECTION).
3. Testing:
   • Unit Tests: Verify critical paths post-refactor.
   • E2E Tests: Smoke test key features (e.g., API routes, jobs).
   • Manual Review: Focus on high-risk areas (e.g., facades, factories).

Compatibility

• Laravel Versions: Supports Laravel 5.8–13.x (check LaravelLevelSetList for target versions).
• Rector Version: Requires Rector 1.0+ (latest stable). Mitigation: Pin version in composer.json.
• Custom Code: Rules may fail on non-standard Laravel usage (e.g., custom facades, macros). Mitigation: Exclude problematic files or override rules.
• Third-Party Packages: Rules for Cashier/Livewire may conflict with custom implementations. Mitigation: Test in isolation.

Sequencing

Operational Impact

Maintenance

• Dependency Updates: Monitor Rector and rector-laravel for breaking changes (e.g., new Laravel versions).
• Rule Maintenance: Custom rules may need updates if Laravel core changes (e.g., new facade methods).
• Configuration Drift: Manual set selections may diverge from auto-detected rules. Mitigation: Document config in rector.php.
• Tooling: Requires Rector CLI familiarity for advanced use (e.g., parallel processing).

Support

• Debugging Refactors:
  • Use --verbose for detailed logs.
  • Check rector:diff to compare before/after changes.
• Community Support:
  • GitHub Issues/Discussions for rule-specific problems.
  • Rector’s Slack/Discord for general questions.
• Custom Rules: Team must maintain project-specific rules (e.g., composer make:rule).

Scaling

• Large Codebases:
  • Parallel Processing: Use --parallel to speed up refactoring.
  • Incremental Commits: Split refactors into smaller PRs (e.g., one set per PR).
• Performance:
  • Caching: Enable --cache to avoid reprocessing unchanged files.
  • Exclusions: Skip vendor/, node_modules/ via --exclude-paths.
• Distributed Teams:
  • Documentation: Maintain a RECTOR_MIGRATION.md with rules applied and rationale.
  • Review Process: Require manual approval for opinionated refactors.

Failure Modes

Ramp-Up

• Onboarding:
  • Workshop: