Rector Doctrine Laravel Package

Technical Evaluation

Architecture fit. rector/rector-doctrine is not a runtime library — it is a rule pack that plugs into rector/rector as a dev-only dependency and participates in the build/CI layer rather than the application architecture. That makes it architecturally low-risk: it never ships to production, adds no runtime surface area, and its removal is a one-line composer remove --dev. For a team already running Rector, the fit is essentially free; for a team that does not run Rector, this package is not adoptable in isolation because it has no entry point of its own. The realistic positioning is "an accelerator inside an existing upgrade factory," not a standalone capability.

Integration feasibility. Mechanically trivial: composer require --dev rector/rector-doctrine, then reference the shipped sets from rector.php (annotation-to-attribute conversion, Doctrine version-targeted rewrites, and code-quality rules over entities, repositories, and collection usage). The real feasibility question is review capacity, not installation. Automated rewrites of mapping metadata are the class of change where "it compiles" is a weak signal — a wrong #[ORM\Column] attribute or a subtly altered association mapping yields a valid PHP file with a broken persistence model. Integration must therefore be paired with a semantic gate (doctrine:schema:validate, schema diff against a known-good database, integration tests against a real engine), not just a green CI build.

Technical risk. Blast radius is small; correctness risk is moderate and concentrated:

• Silent semantic drift. Rector rules are syntax-driven. Rules that touch mapping metadata, association owning/inverse sides, or collection semantics can produce code that parses and passes unit tests while changing generated SQL. Treat every diff in an entity or mapping file as requiring human sign-off.
• Coverage gaps. The rule set is a subset of Doctrine's API surface and deprecation map. Partial automation is the norm; budget for the long tail to be finished by hand and do not present the tool as "complete migration."
• Version coupling. The package tracks Rector majors and Doctrine majors independently, so a Rector bump or a Doctrine 2→3 move can strand you on an unsupported combination. Pin both.
• Adoption signal is weak. 80 stars, 0 tracked dependents, composite score 2.38. This is a small, single-maintainer-adjacent package in a small ecosystem — it is likely better maintained than the metrics suggest (it lives under the rectorphp org), but the numbers mean you should plan for the possibility of forking rather than assuming upstream responsiveness.

Key questions to answer before committing.

1. Which Doctrine ORM/ODM versions and which Rector major does the current release support, and how wide is the support window?
2. What is the rule inventory per set, and what fraction of our actual deprecation surface does it cover? (Grep our codebase against the rule list rather than trusting the README.)
3. Who reviews mapping-level diffs, and do we have a schema-diff gate that would catch a bad rewrite before merge?
4. Do we have a fork-and-maintain contingency, and is the license (MIT) and code size small enough that forking is cheap?
5. How does it compose with phpstan-doctrine and our existing static analysis — overlapping rules, conflicting fixes, or complementary?

Integration Approach

Stack fit. Suitable for any Laravel/PHP service on Doctrine ORM or ODM where Rector is already or can be introduced as a dev dependency. Laravel shops running Eloquent get no value here; this is specifically for the Doctrine-backed portions of the estate (common in legacy modules, DDD-style bounded contexts, or Symfony-adjacent services inside a larger PHP portfolio). Confirm the actual Doctrine footprint first — the addressable surface is often a handful of modules rather than the whole monolith.

Migration path. Three credible entry points, in increasing ambition:

1. Opportunistic — add the package, run it in dry-run against a single module during an unrelated upgrade, cherry-pick safe rules (imports, obvious API renames).
2. Structured — make it a named step in a defined Doctrine upgrade playbook: baseline → dry-run diff review → batch apply per bounded context → schema validate → integration tests → merge.
3. Fork — vendor the package internally if upstream stalls or if you need org-specific rules (in-house base entity conventions, custom mapping drivers). MIT license and modest size make this viable.

Starting at (1) to generate evidence, then deciding between (2) and (3), is the right sequencing. Do not open with a monolith-wide apply.

Compatibility and sequencing. Order matters more than configuration:

1. Freeze the Doctrine and Rector versions; record the supported matrix.
2. Establish the safety net before the first automated rewrite: full test suite, doctrine:schema:validate in CI, and a schema-diff check against a reference database.
3. Run Rector in --dry-run on the whole codebase to size the diff, segmented by rule set — this produces the actual coverage number you were guessing at.
4. Apply lowest-risk sets first (imports, naming, deprecation shims), highest-risk sets (entity mapping, associations, inheritance) last and per-module.
5. Re-baseline PHPStan between batches so new findings are attributable.

Sequencing constraint to respect: do not run this concurrently with a framework major upgrade. Two simultaneous automated rewrite streams make regressions unattributable and turn bisection into guesswork.

Operational Impact

Maintenance. A dev-only dependency with a narrow, well-understood failure surface — but it is a build-tool dependency, meaning breakage blocks CI rather than production. Pin exact versions, keep it out of the runtime lockfile path, and schedule a deliberate review each time Rector or Doctrine majors move. The fork contingency should be documented, not improvised; a one-page "how we'd take this in-house" note is cheap insurance against a stalled upstream.

Support. No commercial support, no SLA. Community issues on a low-traffic repository — expect days-to-weeks, and expect to solve edge cases yourself. Treat vendor responsiveness as best-effort and plan the upgrade calendar around our capacity, not upstream's release cadence.

Scaling. Two dimensions:

• Codebase size — Rector runs are CPU- and time-intensive on large trees. Segment by directory or bounded context and run per-module in CI so a full sweep stays within a tolerable pipeline budget. Cache Rector results where the CI runner allows.
• Team size — the review bottleneck scales linearly with mapping-level diffs and does not parallelize well, because reviewers need Doctrine mapping expertise. This, not compute, is the real ceiling. Budget reviewer time explicitly in the upgrade plan; a rule pack that generates 400 entity diffs has created 400 review tasks, not saved 400 tasks.

Failure modes to instrument.

Ramp-up. Low for anyone who has used Rector (config-driven, familiar --dry-run / --dry-run --diff workflow, maybe half a day). The non-obvious cost is Doctrine mapping literacy on the review side: an engineer who can run Rector is not automatically qualified to approve an association-mapping rewrite. Identify that reviewer before the first batch, not after.

Bottom line for a TPM. Low-risk, narrow-value tool that is worth adopting if and only if you are already running Rector and have a Doctrine upgrade on the roadmap. The 2.38 score and thin adoption are not disqualifying — the blast radius is genuinely small and MIT licensing makes exit cheap — but they do argue against making it a load-bearing part of a migration commitment. Position it as a productivity accelerant inside a human-supervised upgrade playbook, with the schema-diff gate and a named mapping reviewer as non-negotiable prerequisites. Fund it at the scale of a pilot on one module to generate a real coverage number before committing team capacity to a broader program.