Rector Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Specific Transformation: The package is a specialized extension of Rector, a PHP refactoring tool, designed exclusively for Laravel applications. It aligns perfectly with Laravel’s evolutionary upgrade path, automating breaking changes (e.g., Facade deprecations, Eloquent API shifts, Container method updates) and enforcing best practices (e.g., type declarations, DI over static calls).
• Modular Rule Design: Rules are granular and version-targeted (e.g., LaravelLevelSetList::UP_TO_LARAVEL_130), enabling incremental adoption without forcing full migrations. This fits well with strategic tech debt reduction in large codebases.
• Opinionated vs. Configurable: The package balances opinionated refactors (e.g., blank()/filled() helpers) with configurable rules (e.g., RouteActionCallableRector), allowing teams to tailor transformations to their needs.

Integration Feasibility

• Low Friction: Requires only a dev dependency (composer require --dev driftingly/rector-laravel) and minimal config (e.g., LaravelSetProvider for auto-detection or explicit sets like LARAVEL_STATIC_TO_INJECTION).
• CI/CD Friendly: Designed for automated pipelines (e.g., GitHub Actions), with dry-run support via Rector’s --dry-run flag. Ideal for pre-merge validation of refactors.
• IDE Compatibility: Rules like LARAVEL_FACTORIES improve IDE tooling (e.g., autocompletion for factories), reducing manual maintenance overhead.

Technical Risk

• False Positives/Negatives: Some rules (e.g., WhereToWhereLikeRector) require database-specific config (USING_POSTGRES_DRIVER), risking incorrect refactors if misconfigured. Mitigation: Test in a staging environment first.
• Breaking Changes: While the package avoids introducing breaking changes itself, applying its rules may expose underlying Laravel deprecations. Mitigation: Use rector process in small batches with versioned commits.
• Custom Logic: Opinionated rules (e.g., ResponseHelperCallToJsonResponseRector) may conflict with team conventions. Mitigation: Review rules before bulk application.

Key Questions

1. Upgrade Strategy:
   • Are we targeting specific Laravel version upgrades (e.g., 10→11) or proactive code quality (e.g., LARAVEL_CODE_QUALITY)?
   • Should we phase refactors (e.g., DI first, then Facade aliases) or apply all at once?
2. Testing Coverage:
   • How will we validate refactored code? (e.g., regression tests, manual review of critical paths).
   • Can we auto-generate test cases for transformed logic (e.g., using Pest or PHPUnit)?
3. Team Buy-In:
   • Will developers understand the refactors? (Documentation/education plan needed for rules like UseForwardsCallsTraitRector).
   • How will we handle disagreements on opinionated rules (e.g., RemoveDumpDataDeadCodeRector)?
4. Performance Impact:
   • Will refactors (e.g., LARAVEL_COLLECTION optimizations) improve runtime performance, or are they purely syntactic?
5. Long-Term Maintenance:
   • How will we keep Rector/Laravel rules updated as Laravel evolves? (e.g., subscribing to Rector’s release cycle).

Integration Approach

Stack Fit

• Primary Use Case: Laravel monorepos or large applications with legacy codebases needing modernization.
• Complementary Tools:
  • Rector Core: Handles PHP-level refactors (e.g., PHP 8.1+ attributes).
  • Laravel Pint: For consistent code formatting post-refactor.
  • PHPStan/Psalm: For static analysis to catch type-related issues introduced by rules like LARAVEL_TYPE_DECLARATIONS.
• Anti-Patterns:
  • Avoid using in small projects where manual upgrades are faster.
  • Not suitable for non-Laravel PHP projects (use rector/rector core instead).

Migration Path

1. Assessment Phase:
   • Run rector process --dry-run with targeted sets (e.g., LaravelLevelSetList::UP_TO_LARAVEL_110) to identify high-risk files.
   • Use rector process --diff to preview changes.
2. Pilot Phase:
   • Apply rules to non-critical modules (e.g., feature branches) and validate with automated tests + manual QA.
   • Focus on low-risk sets first (e.g., LARAVEL_ARRAYACCESS_TO_METHOD_CALL).
3. Full Rollout:
   • Batch by component: Start with API services, then admin panels, finally frontend.
   • Versioned commits: Use git commit -m "Apply Rector: Laravel 11 Facade updates" for traceability.
4. Post-Migration:
   • Update CI pipelines to run Rector as a pre-commit hook or merge check.
   • Monitor error logs for refactor-related issues (e.g., ClassNotFoundException from LARAVEL_CONTAINER_STRING_TO_FULLY_QUALIFIED_NAME).

Compatibility

• Laravel Versions: Supports Laravel 8+ (check LaravelLevelSetList for version-specific rules).
• PHP Versions: Requires PHP 8.0+ (Rector’s baseline).
• Dependency Conflicts:
  • Ensure no version clashes with other Rector packages (e.g., rector/rector).
  • Test with custom service providers or package-specific rules (e.g., Livewire/Cashier).
• Database Schemas: Rules like WhereToWhereLikeRector may require SQL adjustments if migrating between DBMS (e.g., MySQL → PostgreSQL).

Sequencing

Operational Impact

Maintenance

• Rule Updates:
  • Proactive: Subscribe to Rector’s changelog and rector/rector-laravel updates.
  • Automated: Use composer outdated to monitor for new rule versions.
• Custom Rules:
  • Extend the package via composer make:rule for project-specific refactors.
  • Maintain a fork if upstream rules become incompatible with legacy Laravel versions.
• Documentation:
  • Internal wiki to document:
    • Applied rule sets and their justification.
    • Exclusions (e.g., files/rules skipped due to risk).
    • Rollback procedures (e.g., git revert for bulk changes).

Support

• Troubleshooting:
  • Common Issues:
    • ClassNotFoundException: Fix with composer dump-autoload.
    • MethodNotFoundException: Check Laravel version compatibility.
    • False positives: Override rules in rector.php (e.g., @ignoreNext annotations).
  • Debugging: Use rector process --verbose and check Rector’s issue tracker for known bugs.
• Team Training:
  • Workshops: Demo Rector’s dry-run mode and rule customization.
  • Cheat Sheet: List of high-impact rules and their expected outcomes (e.g., "This rule replaces abort() with `abort_if