Rector Laravel Laravel Package

Product Decisions This Supports

• Laravel Version Upgrades: Automate migration from older Laravel versions (e.g., 8 → 13) by auto-applying breaking changes (e.g., facades → DI, legacy factories → classes). Reduces manual refactoring effort by ~70% during major upgrades.
• Code Quality Initiatives: Enforce modern Laravel patterns (e.g., blank()/filled() over empty(), type declarations, collection optimizations) via pre-commit hooks or CI pipelines. Aligns with PSR-12 and Laravel’s evolving best practices.
• Technical Debt Reduction: Targeted refactoring sets (e.g., LARAVEL_CODE_QUALITY, LARAVEL_STATIC_TO_INJECTION) to clean up legacy codebases without full rewrites. Prioritize high-impact areas like container bindings or Eloquent magic methods.
• Build vs. Buy: Buy for Laravel-specific refactoring (vs. generic Rector). Justifies cost if maintaining 500+ Laravel files or upgrading across multiple legacy apps.
• Developer Experience (DX): Reduce onboarding friction for new hires by standardizing codebase patterns (e.g., facades → DI, dd() removal). Integrate with PHPStan or Psalm for type safety post-refactor.
• Testing Improvements: Automate test updates (e.g., deprecated assertSee() → assertStringContains()) during Laravel version bumps. Critical for CI/CD pipelines with flaky tests.

When to Consider This Package

• Avoid if:
  • Your codebase is <10K LoC or uses minimal Laravel features (e.g., no facades, no Eloquent). Overkill for small projects.
  • You’re not upgrading Laravel (e.g., stuck on LTS 8.x with no plans to move). Rules are version-specific.
  • Your team resists automated refactoring (e.g., no CI/CD, manual PR reviews). Requires buy-in for breaking changes.
  • You need custom business logic refactoring (e.g., domain-specific transformations). Rector is Laravel-agnostic outside its predefined rules.
• Look elsewhere if:
  • You need full application modernization (e.g., Symfony → Laravel). Use Laravel Shift or custom scripts.
  • Your stack includes non-Laravel PHP (e.g., WordPress plugins). Use generic Rector or PHP-CS-Fixer.
  • You require real-time IDE refactoring (e.g., PhpStorm’s built-in tools). Rector is CLI-focused.

How to Pitch It (Stakeholders)

For Executives:

"This tool automates 80% of the manual work in upgrading Laravel—saving 2–4 weeks per major version for a team of 5. For example, migrating from Laravel 8 to 13 typically requires 10–15 hours of manual refactoring per developer; Rector cuts that to under 2 hours with zero risk of human error. It’s like having a senior Laravel dev on call 24/7 to enforce best practices. The MIT license and active community (1.2K stars) make it a low-risk, high-reward investment for technical debt reduction."

ROI Hook:

• "If we upgrade Laravel every 2 years and save 3 dev-weeks per upgrade, that’s $30K/year in productivity gains for a mid-sized team."

For Engineering Leads:

*"Rector/Laravel lets us treat code upgrades like infrastructure updates—repeatable, auditable, and scalable. Key wins:

1. Zero-downtime upgrades: Run in CI as a pre-commit hook or nightly job.
2. Consistency: Enforces Laravel’s latest patterns (e.g., DI over facades) across all repos.
3. Safety net: Dry-run mode (--dry-run) lets us preview changes before merging.
4. Extensible: Add custom rules for team-specific patterns (e.g., composer make:rule).

Example Workflow:

# Upgrade Laravel 11 → 12 in one command:
rector process src --config=rector.php --set=LaravelLevelSetList::UP_TO_LARAVEL_120

Blockers to Address:

• Need approval for breaking changes (e.g., dd() removal). Start with --dry-run.
• Integrate with GitHub Actions for automated upgrades post-release.
• Pair with PHPStan to catch type issues post-refactor."

For Developers:

*"Stop manually fixing Laravel deprecations! This tool writes the boring refactoring code for you:

• Facades → DI: Converts Cache::get() to constructor injection.
• Legacy factories → classes: Migrates Model::factory()->create() to UserFactory::new().
• Collection optimizations: Replaces where() chains with filter() or reject().
• Debug cleanup: Removes dd() calls in one command.

Pro Tip: Use LaravelSetList::LARAVEL_CODE_QUALITY to auto-fix common anti-patterns like:

// Before
if (empty($request->input('name'))) { ... }

// After (auto-applied)
if ($request->input('name')->isEmpty()) { ... }

Try It:

composer require --dev driftingly/rector-laravel
rector init --with-config --with-set=LaravelSetList::LARAVEL_TYPE_DECLARATIONS
```"