Rector Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Laravel 13+ Specific Enhancements: The 2.3.0 release introduces Laravel 13-specific rules (e.g., Model Attributes, Queue Job attributes, and PreventRequestForgery middleware renaming), aligning with Laravel’s latest syntax and best practices. This strengthens the package’s role in modernizing Laravel 13+ codebases while maintaining backward compatibility for older versions via version-specific sets.
• Improved Rule Granularity: New rules like UseSingleQueueableTraitInJobs and fixes for ValidationRuleArrayStringValueToArrayRector demonstrate refined targeting of Laravel’s evolving patterns, reducing false positives in complex scenarios (e.g., closures in rules() methods).
• Rector Core Integration: The upgrade to Rector ^2.4.1 (PR #492) ensures compatibility with modern Rector features (e.g., getFile() API), future-proofing the package while maintaining AST-based safety.

Integration Feasibility

• Laravel 13 Support: Explicit LARAVEL_130 set (PR #485) simplifies adoption for teams upgrading to Laravel 13, with auto-detection via LaravelSetProvider.
• Dependency Stability: Minor dependency updates (e.g., webmozart/assert ^2, ramsey/composer-install ^4) are non-breaking and align with modern PHP tooling.
• Livewire 4.0 Fixes: PR #480 addresses associative array handling in RenameClassRector, reducing edge-case failures in Livewire-heavy applications.
• PHPUnit Integration: PR #479 standardizes test suite handling, improving compatibility with Laravel’s testing ecosystem.

Technical Risk

• Breaking Changes:
  • Laravel 13-Only Rules: New rules (e.g., Model Attributes) will not apply to pre-Laravel 13 codebases unless explicitly configured. Mitigation: Use UP_TO_LARAVEL_130 for incremental upgrades.
  • Middleware Renaming: CSRF middleware → PreventRequestForgery (PR #484) may break custom middleware configurations. Risk is limited to Laravel 13+ users.
• Rule Precision:
  • Validation Rules Fix: PR #475 resolves closure processing in rules() methods, but complex nested rules may still require manual review.
  • Queueable Trait Rule: PR #462’s UseSingleQueueableTraitInJobs could over-apply in multi-trait scenarios. Test with --dry-run first.
• Performance:
  • Rector 2.4.1: Minor overhead from new rule sets, but parallel processing (--parallel) remains effective for large codebases.
• Customization Limits:
  • PHPStan Compatibility: Fixes (e.g., PR #490) reduce errors but may not cover all edge cases in strict PHPStan setups.

Key Questions

1. Laravel 13 Adoption:

   • Should we target LARAVEL_130 immediately or use UP_TO_LARAVEL_130 for phased upgrades?
   • How will we handle mixed-version dependencies (e.g., packages using Laravel 12 patterns)?

2. Rule Safety:

   • Which opinionated Laravel 13 rules (e.g., Model Attributes) should be opted into incrementally?
   • Should we disable auto-detection for LaravelSetProvider to avoid unintended rule application?

3. Testing Impact:

   • How will Model Attributes (e.g., $table, $fillable) affect serialization/deserialization in APIs?
   • Should we extend test coverage for Queueable trait changes (PR #462)?

4. CI/CD Strategy:

   • Should we gate Laravel 13-specific rules in CI until full validation?
   • How will we audit middleware changes (e.g., PreventRequestForgery) in legacy routes?

5. Long-Term Maintenance:

   • Who will update rules for Laravel 14+ (e.g., new attribute syntax)?
   • Should we fork custom rules for internal Laravel extensions (e.g., custom attributes)?

Integration Approach

Stack Fit

• Primary Use Case: Laravel 13+ modernization, especially for teams using:
  • Model Attributes (e.g., $casts, $attributes).
  • Queue Job Attributes (e.g., @onQueue).
  • Livewire 4.0 or CSRF middleware updates.
• Complementary Tools:
  • Laravel Pint: Pair with LARAVEL_CODE_QUALITY for consistent formatting.
  • PestPHP: Leverage LARAVEL_TESTING rules for cleaner test syntax.
  • Tinkerwell: Debug refactored attribute logic interactively.
• Anti-Patterns:
  • Avoid in Laravel <13 without UP_TO_LARAVEL_130 set.
  • Not suitable for custom attribute-based systems (e.g., non-Laravel ORMs).

Migration Path

1. Assessment Phase:

   • Audit: Identify Laravel 13+ usage (e.g., use Illuminate\Database\Eloquent\Concerns\HasAttributes).
   • Dry Run: Test LARAVEL_130 set with --dry-run to preview changes.
   • Tooling: Update rector.php to include:

     use Rector\Config\RectorConfig;
     use Rector\Set\LaravelSetList;
     
     return RectorConfig::create()
         ->withSets([
             LaravelSetList::LARAVEL_130,
             LaravelSetList::CODE_QUALITY,
         ]);
     

2. Pilot Phase:

   • Scope: Apply to non-critical modules (e.g., feature flags, non-core APIs).
   • Rules: Enable Model Attributes and Queueable Trait rules separately for validation.
   • Validation: Test:
     • Model serialization (e.g., json_encode($model)).
     • Queue job dispatching (e.g., YourJob::dispatch()->onQueue('critical')).

3. Full Rollout:

   • Phased by Feature: Prioritize:
     1. Models (Attributes, casts).
     2. Jobs (Queueable trait).
     3. Middleware (CSRF updates).
   • CI Integration: Add to pre-merge checks with:

     # GitHub Actions example
     - name: Run Rector
       run: rector process src --set=LARAVEL_130 --level=max --dry-run
     

   • Post-Refactor: Clean up dead code (e.g., removed $table property) and update tests.

Compatibility

• Laravel Versions:
  • Supported: 13.x (full), 8.x–12.x (via UP_TO_LARAVEL_130).
  • Unsupported: Laravel <8 (AST limitations).
• PHP Versions: Requires PHP 8.1+ (Rector 2.4.1 baseline).
• Dependency Conflicts:
  • Livewire 4.0: Fixed in PR #480; ensure livewire/livewire:^4.0 is used.
  • PHPUnit: PR #479 standardizes suite handling; update phpunit/phpunit:^10.0 if needed.
• Database Schema: No impact, but Model Attributes may require:
  • Updated migrations if using $table attribute.
  • Index adjustments for query builder changes (e.g., whereLike()).

Sequencing