Rector Laravel Laravel Package

Technical Evaluation

Architecture fit

driftingly/rector-laravel is a rule pack that extends Rector, a PHP AST-based refactoring engine. It is not a runtime library — it installs as a require-dev dependency and operates over source files at build/upgrade time. Architecturally this is a very clean fit for any Laravel estate:

• Zero production footprint. Nothing ships to runtime; no autoload weight, no service provider, no config surface to maintain in the deployed app.
• Composable with the existing toolchain. It plugs into the same rector.php config object that teams already use for Rector, so it composes with other Rector extensions and rules rather than introducing a parallel tool.
• Version-aware by design. RectorConfig::configure()->withComposerBased(laravel: true) reads composer.json and applies only the rule sets up to the installed Laravel (plus Faker, Livewire, Cashier) version. This turns "upgrade Laravel" from a bespoke migration project into a deterministic, repeatable transformation — the single strongest architectural argument for adoption.
• Two distinct value modes. (1) Upgrade automation — version sets (LaravelLevelSetList, LaravelSetList::LARAVEL_130, etc.) that encode the Laravel upgrade guide as executable rules. (2) Codebase modernisation — opt-in sets for code quality, collections, DI conversion, type declarations, testing. These are separable and can be sequenced, which matters for risk management.
• Extensible. composer make:rule scaffolding plus a documented directory/namespace convention means an internal platform team can encode house rules (e.g., banned helpers, mandated JsonResponse) into the same pipeline.

The main architectural caveat is that the package inherits Rector's model: it is a source-to-source rewriter with no semantic guarantee. Fit is high; trust is not implicit and must be earned through test coverage and diff review.

Integration feasibility

Feasibility is high and the effort is measured in hours, not sprints:

• composer require --dev driftingly/rector-laravel (pulls in rector/rector as a peer).
• Add rector.php returning RectorConfig::configure()->withComposerBased(laravel: true) — this single line replaces the deprecated LaravelLevelSetList::UP_TO_LARAVEL_* constants and auto-selects rules.
• Run vendor/bin/rector process --dry-run first, review the diff, then vendor/bin/rector process.

Constraints to validate before committing:

• Rector major-version compatibility. The config API shown (RectorConfig::configure()) is Rector 2.x-era. Confirm the installed Rector version matches what the package's current release targets, and pin both.
• PHP version supported by the Rector runtime and by the target codebase.
• Laravel coverage ceiling. The docs advertise sets up to Laravel 13, but releases are dated in the future relative to typical consumption (metadata shows 2026-10-27) — treat the version matrix as something to verify against Packagist rather than assume.
• Framework extensions. First-party ecosystem packages are partially covered (Cashier, Livewire, Faker); anything else (Nova, Filament, Inertia, Sanctum) relies on generic Laravel/community rules and needs manual review.
• Scope boundaries. PHP only. Blade templates, config files evaluated at runtime, and dynamic dispatch via app(), string container bindings, or call_user_func are the known blind spots — several rules exist precisely because those patterns are hard to reason about statically.

Technical risk

Risk is concentrated in semantic drift from automated edits, not in the dependency itself. Key exposures:

Key questions

1. Which Laravel and PHP version ranges does the current release actually support, and how quickly are new Laravel majors covered after release?
2. What is the guaranteed-compatible Rector version, and what is the policy when Rector ships a breaking change?
3. Do individual rules have test fixtures, and is there any published measure of false-positive rate or idempotency?
4. Is withComposerBased reliable in monorepos / multi-composer.json workspaces, or does each package need its own config?
5. Who owns this internally — is there a named platform owner, or is it an unowned "tool someone added"?
6. For semantics-changing rules, is there an agreed review protocol (migration guide cross-check + test suite green) before merge?

Integration Approach

Stack fit

Excellent for a standard Composer-based Laravel monolith or a set of Laravel services. The package is a dev-only Composer dependency with no runtime coupling, so it slots into the existing composer.json, CI pipeline, and code review process without touching application architecture. The only prerequisite is that the repo already has (or can adopt) a test suite adequate to catch semantic drift — this tool amplifies test coverage; it does not substitute for it.

Migration path

Phased, with escalating blast radius:

1. Discovery (no writes). Add the dependency on a branch, write a minimal rector.php with only the version set for the current Laravel version, and run --dry-run. The resulting diff tells you what the tool thinks your codebase is doing wrong. This is the cheapest possible signal.
2. Baseline adoption. Commit the config, add a CI job that runs rector process --dry-run in report-only mode. No gate yet — just visibility and a stable config.
3. Version-upgrade enablement. Make the package the standard first step of every Laravel bump: bump laravel/framework, run Rector, review diff, ship. This is the highest-ROI use and the one with the clearest acceptance criteria (tests pass + upgrade guide items covered).
4. Selective modernisation. Enable one code-quality set at a time (LARAVEL_CODE_QUALITY, LARAVEL_COLLECTION, LARAVEL_TESTING, LARAVEL_TYPE_DECLARATIONS) scoped by directory via Rector paths. One PR per set, one reviewer, full test run.
5. House rules. Only if a platform team wants to own it — use composer make:rule to encode internal conventions so the same pipeline enforces them.

Compatibility

• Pin driftingly/rector-laravel and rector/rector together in composer.json; treat them as a paired version set.
• Prefer withComposerBased(laravel: true) over the deprecated LaravelLevelSetList::UP_TO_LARAVEL_* constants — the manual sets are slated for removal in a future major.
• In a monorepo, configure per package rather than one root config, otherwise version detection resolves against the wrong composer.json.
• Keep third-party Rector extensions (e.g., for other frameworks or PHPStan bridges) in a separate config include so a failure in one doesn't block the Laravel rules.

Sequencing

Version/upgrade sets → framework-adjacent correctness (LARAVEL_TESTING, LARAVEL_TYPE_DECLARATIONS) → ergonomics (LARAVEL_COLLECTION, LARAVEL_IF_HELPERS) → architectural rewrites (LARAVEL_STATIC_TO_INJECTION, LARAVEL_ELOQUENT_MAGIC_METHOD_TO_QUERY_BUILDER) → opinionated/configured rules on explicit request only. Never enable an architectural set in the same PR as a framework upgrade; you lose the ability to attribute a failure.

Operational Impact

Maintenance

Low steady-state cost: bump the dev dependency on the same cadence as Rector and Laravel; verify the version sets cover the target Laravel release before starting an upgrade. The real maintenance obligation is config hygiene — a rector.php that grows without review becomes an unreviewable source of diffs. Assign a named owner (platform/DevEx) and treat the config as code.

Support

MIT-licensed, community-maintained, no commercial SLA. Support is GitHub issues plus the Rector rule-finder site. Escalation path for a broken rule is to disable it, file an issue, or write a local equivalent. Budget for the possibility of self-support on edge cases; this is not a vendor you can escalate to.

Scaling

Runtime scales with codebase size and rule count; Rector is CPU-bound and parallelisable across paths. For large codebases, shard by directory in CI and keep the dry-run job on a schedule rather than every PR if wall-clock becomes painful. Organisationally, scaling means a shared base rector.php published internally so teams don't diverge, plus a per-team opt-in for opinionated rules.

Failure modes

• Silent semantic change merged because tests didn't cover the path — mitigated by mandatory diff review and upgrade-guide cross-check on behaviour-changing rules.
• Partial application — Rector aborts mid-run on a parse/rule error, leaving a half-transformed working tree. Always run on a clean branch and treat a non-zero exit as "discard and investigate", not "patch by hand".
• Config drift between repos producing inconsistent conventions.
• Lockfile conflicts when the pinned Rector version disagrees with another Rector extension.
• Version-detection blind spot in monorepos leading to rules applying for the wrong target version.
• CI noise if dry-run is made a hard gate too early — expect a large initial diff and stage the gate after the baseline is cleaned.

Ramp-up

Very fast for consumers: two commands to install and configure, one config line for version-aware operation, and the docs are good enough that a mid-level engineer can run their first upgrade pass unaided. Ramp-up is materially higher only for rule authoring (understanding Rector's node types and fixture testing) — plan a short internal enablement session if a team intends to encode house rules. Overall: adopt with confidence as a dev-only upgrade accelerator, gate it behind tests and review, and keep the opinionated rules off by default.