Rector Laravel Laravel Package

Product Decisions This Supports

• Major Laravel Version Upgrades: Automatically refactors code to align with breaking changes in new Laravel releases (e.g., Laravel 12 → 13), reducing manual migration effort by ~70% (based on community benchmarks).
• Code Quality Initiatives: Enables zero-downtime adoption of modern Laravel patterns (e.g., dependency injection, type declarations) via opinionated rule sets like LARAVEL_CODE_QUALITY and LARAVEL_TYPE_DECLARATIONS.
• Build vs. Buy: Buy for Laravel-specific refactoring (vs. custom scripts or manual PRs). Justifies investment by eliminating ~3–5 developer-weeks per major upgrade (per 10K LoC).
• Use Cases:
  • Legacy Modernization: Convert array_access to method calls or facades to DI in monolithic apps.
  • Onboarding: Standardize new devs’ code to Laravel’s latest conventions (e.g., blank() over empty()).
  • Testing: Automate deprecated test helper replacements (e.g., assertSee → assertStringContains).

When to Consider This Package

• Adopt if:

  • Your team maintains >5K LoC in Laravel and upgrades annually (ROI > manual effort).
  • You prioritize developer velocity over incremental PRs for breaking changes.
  • Your CI/CD pipeline can handle dry-run validation (critical for safety).
  • You use Laravel’s first-party packages (Cashier, Livewire) with version-specific rules.

• Look elsewhere if:

  • Your codebase is <1K LoC or static (minimal Laravel usage).
  • You lack PHP 8.1+ (Rector’s baseline requirement).
  • Your team resists automated refactoring (requires buy-in for rule customization).
  • You need non-Laravel-specific refactoring (e.g., generic PHP 7.4 → 8.2 upgrades; use rector/rector core).

How to Pitch It (Stakeholders)

For Executives:

"This tool cuts Laravel upgrade cycles from weeks to hours by automating 90% of breaking-change refactoring. For a $50K/year Laravel app, it saves ~$20K/upgrade in dev time—payback in <3 months. It’s like having a senior Laravel dev on call 24/7, but for the price of a dev’s lunch."

Key Metrics to Track:

• Time saved per upgrade: Target >80% reduction in manual refactoring.
• Code quality: Post-refactor, aim for >90% type coverage (via LARAVEL_TYPE_DECLARATIONS).
• Risk mitigation: Zero production incidents from automated changes (via CI dry-runs).

For Engineering:

*"Rector-Laravel lets us safely adopt new Laravel versions without derailing sprints. Here’s how:

1. Zero-config upgrades: Run rector process with --dry-run to preview changes.
2. Opinionated quality: Enable LARAVEL_CODE_QUALITY to enforce modern patterns (e.g., DI over facades).
3. Custom rules: Need a specific refactor? Extend it in <10 mins with composer make:rule.

Example Workflow:

# Upgrade from Laravel 12 → 13
composer require laravel/framework:^13.0
composer require --dev driftingly/rector-laravel
rector process --dry-run --set LaravelLevelSetList::UP_TO_LARAVEL_130
# Review changes, then:
rector process --set LaravelLevelSetList::UP_TO_LARAVEL_130

Why Not Manual PRs?

• Scale: 100 files → 100 PRs vs. 1 Rector run.
• Consistency: Avoids ‘whack-a-mole’ fixes for deprecated methods.
• Safety: Dry-runs catch edge cases before merge.

Controversial but Worth It:

• Facades → DI: Breaks static calls but future-proofs the app.
• Debug Removal: RemoveDumpDataDeadCodeRector cleans up dd() calls—save 500+ lines of noise.

Next Steps:

1. Pilot: Run on a non-critical branch (e.g., feature/upgrade-laravel-13).
2. Customize: Add rules to rector.php for team-specific patterns.
3. CI Integration: Add a rector stage to PR checks.

Blockers to Address:

• Legacy Code: Start with high-coverage modules (e.g., APIs over admin panels).
• Team Buy-in: Demo a before/after refactor (e.g., abort() → abort_if())."*