Product Decisions This Supports
- Roadmap sequencing for the Doctrine ORM 2.x → 3.x upgrade. Doctrine 3 removes the annotation driver, so any codebase mapping entities via docblock annotations has a hard, non-optional migration in front of it. This package gives that workstream a concrete "automate first, hand-fix the remainder" plan instead of an open-ended manual rewrite, which is the single biggest input into whether the upgrade lands this quarter or slips.
- Build vs. buy on internal codemods. The alternative is writing and maintaining your own Rector rules for the same transformations. This ruleset is an MIT-licensed starting point; the buy case is strong because the rules are deterministic, the output is a reviewable diff, and forking is always available if upstream stalls.
- Budgeting migration effort. Because the tool tells you which files it can transform automatically versus which need human judgment, it converts a vague "Doctrine upgrade: 6–8 weeks?" line item into a measurable one: run it in dry-run mode against the repo, count transformed files, and size the remainder. That's a decision-grade estimate you can defend to finance.
- Tech-debt and platform-modernization OKRs. "Percent of deprecated ORM/annotation usage eliminated" is a trackable metric, and this tool produces it as a by-product of running in CI.
- Standing CI guardrail vs. one-off script. Two product postures: adopt it as a dev dependency with a pinned ruleset applied on every PR (prevents regression toward deprecated patterns), or run it once as a throwaway codemod container. The one-off posture is the lower-commitment entry point and is usually the right first step.
- Use cases where it pays off: monorepos and long-lived Symfony/Laravel apps with a Doctrine domain layer, teams with a large entity/repository surface, and any migration where review bandwidth — not engineering skill — is the bottleneck.
Adoption signal is thin, and that should shape the decision, not block it. 80 stars and zero dependents means no crowd-sourced validation. But this is a dev-time, narrow-scope, MIT-licensed tool with no runtime footprint and no production blast radius — the failure mode is "the codemod produced a bad diff we review and reject," not an outage. Treat it as a low-risk, low-certainty bet and validate with a trial run rather than a popularity check.
When to Consider This Package
Adopt (or trial) when:
- You have a real Doctrine ORM layer — entities, repositories,
EntityManager, query builders. This is a Doctrine tool; it is not a Laravel/Eloquent tool, and Eloquent-only applications get essentially nothing from it.
- Doctrine mapping still lives in docblock annotations, or you're pinned to a 2.x release and 3.x is on the roadmap.
- Rector is already in the toolchain, or you're willing to adopt it. This package is an extension — it has no standalone value, so the real decision is "adopt Rector," with this as a cheap add-on.
- The codebase is large enough that manual migration cost exceeds the setup and review cost. Below roughly a few dozen entities, hand-editing is faster and clearer.
- You have review capacity to inspect generated diffs. Automation here shifts work from writing to reviewing; it does not eliminate the work.
Look elsewhere or defer when:
- Eloquent-only Laravel app, or Doctrine appears only transitively through a vendor package you don't maintain.
- No Rector adoption and no appetite for it — this package is not the reason to introduce an AST-refactoring layer.
- Your organization requires vendor-supported dependencies or an SLA. This is a small, effectively single-maintainer project; if that's disqualifying for your supply-chain policy, it's disqualifying, full stop.
- You need runtime behavior, monitoring, or framework integration. This is a static code-transformation tool, nothing more.
- The migration is already done, or you're greenfield on Doctrine 3 with attribute mapping from day one — the target state is already your starting state.
Mitigations if you proceed: pin an exact version, commit the config so runs are reproducible, and keep the tool in require-dev with no CI write permissions beyond opening a PR.
How to Pitch It (Stakeholders)
To executives: This is a free, MIT-licensed dev-time tool that automates part of our Doctrine ORM upgrade — a migration we have to do regardless, because the ORM's next major version removes the mapping style our code currently uses. It carries zero production risk: it isn't shipped, it can't affect runtime, and every change it produces arrives as a pull request a human approves. The ask is small — a timeboxed trial against our codebase — and the output of that trial is a real number for how much of the migration is mechanical versus hand-work, which is exactly what we need to commit to a delivery date. The honest caveat: the project has a small user base, so we treat it as an accelerator we can abandon at any point, not a platform we depend on.
To engineering: Rector with the Doctrine ruleset. Rulesets cover annotation-to-attribute conversion and Doctrine API deprecations, run in dry-run first so you see the diff before anything is written. It's deterministic and idempotent — re-running on an already-migrated tree is a no-op, which makes it safe to leave in CI as a guardrail. It won't handle hand-tuned DQL, custom hydrators, or behavioral subtleties in repository code; assume those need eyes. Trial plan: dry-run on a branch, triage the diff into "merge as-is / fix / exclude," and use that triage as the estimate. Keep it in require-dev, pinned, and don't let it hold write access to anything but a PR branch.