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 (facades → DI, legacy factories → classes, string events → dispatcher-scoped events). Reduces manual refactoring effort by ~70% during major upgrades. The rule library now stands at 130 rules (2.7.0), with the newest additions targeting Laravel 11+ idioms — notably CommandPropertyToAsCommandAttributeRector (property-based $signature/$description → #[AsCommand] attribute), which is directly on the critical path for teams moving to attribute-driven Laravel.
• Code Quality Initiatives: Enforce modern Laravel patterns via pre-commit hooks or CI pipelines: blank()/filled() over empty(), CollectionCountComparisonToIsEmptyRector (count($c) === 0 → isEmpty()), type declarations, and collection optimizations. Aligns with PSR-12 and Laravel's evolving best practices.
• Eloquent & Domain-Model Modernization: New rules such as RelationTableStringToPivotClassRector and TablePropertyToTableAttributeRector push stringly-typed relational metadata into typed pivot classes and #[Table] attributes — a concrete, measurable step toward typed models and better static analysis. Treat this as a technical-debt reduction workstream, not just cosmetic cleanup.
• 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 (now resolving named binding arguments), event dispatching (broadcast support added), and Eloquent magic methods.
• Build vs. Buy: Buy for Laravel-specific refactoring (vs. generic Rector). Justifies cost if maintaining 500+ Laravel files, upgrading across multiple legacy apps, or standardizing patterns across repos. The 2.7.0 release shows sustained upstream maintenance (5 new external contributors), which lowers the "abandoned dependency" risk that usually kills buy decisions.
• Developer Experience (DX): Reduce onboarding friction for new hires by standardizing codebase patterns (facades → DI, dd() removal, unlink() → File::delete()). Pairs cleanly with PHPStan/Psalm for post-refactor type safety.
• Supply-Chain & CI Hygiene: Composer metadata now carries keywords that cause Composer to suggest --dev on require, reducing the chance the tool ships to production. Combined with export-ignore for .github, this is a small but real operational win for teams with strict dependency governance.

When to Consider This Package

• Avoid if:
  • Your codebase is <10K LoC or uses minimal Laravel features (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 (no CI/CD, manual PR reviews). Requires buy-in for breaking changes.
  • You need custom business logic refactoring (domain-specific transformations). Rules are Laravel-agnostic outside their predefined set.
• Look elsewhere if:
  • You need full application modernization (e.g., Symfony → Laravel). Use Laravel Shift or custom scripts.
  • Your stack includes non-Laravel PHP (WordPress plugins, standalone packages). Use generic Rector or PHP-CS-Fixer.
  • You require real-time IDE refactoring (PhpStorm built-in tools). Rector is CLI-focused.
• Adopt with guardrails (new in 2.7.0): The release fixes silent model corruption in TablePropertyToTableAttributeRector — a reminder that model-touching rules can produce valid-but-wrong code that tests won't necessarily catch. Mandate: pin the exact version, always run --dry-run first on a branch, review diffs on app/Models and migrations with extra scrutiny, and hold a DB-level regression pass after any Eloquent-related set. Prefer the newest patch over older pins, since correctness fixes are landing continuously.

How to Pitch It (Stakeholders)

For Executives:

"This tool automates most of the manual work in upgrading Laravel — saving 2–4 weeks per major version for a team of 5. Migrating from Laravel 8 to 13 typically requires 10–15 hours of manual refactoring per developer; Rector cuts that to under 2 hours. The 2.7.0 release adds five new rules (130 total) covering modern Laravel conventions like attribute-based commands and typed pivot relations, and fixes several correctness bugs — evidence the project is actively maintained rather than a stalled side project. MIT license, low-risk, high-reward 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, 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 (DI over facades) across all repos.
3. Safety net: --dry-run previews changes before merging; export-ignore and dev-only keywords keep it out of production builds.
4. Extensible: Add custom rules for team-specific patterns (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 (2.7.0 explicitly fixes PHPStan compatibility) to catch type issues post-refactor.
• Version pinning policy: model-rewriting rules have had correctness regressions; require branch + diff review + DB regression suite for any Eloquent set."

For Developers:

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

• Facades → DI: Cache::get() → constructor injection.
• Commands → attributes: $signature/$description properties → #[AsCommand].
• Relations → typed pivots: string pivot tables → pivot classes.
• Collections: count($c) === 0 → isEmpty(); where() chains → filter()/reject().
• File & debug cleanup: unlink() → File::delete(), dd() removal.

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

// Before
if (count($items) === 0) { ... }

// After (auto-applied)
if ($items->isEmpty()) { ... }

Try It:

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

Run --dry-run first; never let it touch app/Models in a PR you haven't eyeballed."