Rector Phpunit Laravel Package

Product Decisions This Supports

• Dependency-upgrade roadmap. This package is a codemod layer, not a runtime dependency: it automates PHPUnit major-version migrations (annotation → attribute, @dataProvider → #[DataProvider], setUp(): void, removed/changed assertions, prophecy and mock-builder deprecations). It directly informs when we can commit to PHPUnit 10/11/12 and, by extension, which PHP versions and Laravel releases we can track.
• Build vs. buy on internal tooling. The alternative is hand-migrating test suites ticket-by-ticket, or writing our own Rector rules. This is buy — MIT-licensed, maintained under the rectorphp org, and sits on a tool (Rector) we may already run for production code. Decision: adopt the rule set rather than fund bespoke codemods.
• Technical-debt and platform-modernization prioritization. Gives a credible, low-cost estimate for "how much of the upgrade backlog is mechanical?" If 70%+ of a PHPUnit bump is automatable, the upgrade moves up the roadmap and shrinks the associated epic.
• Engineering-velocity and CI health. Faster framework/runtime upgrades mean security patches land sooner, and the test suite stays on a supported PHPUnit branch instead of being pinned and unmaintained.
• Risk sizing for large test suites. The dry-run diff output is a scoping artifact: run it, count changed files, and you have a defensible size estimate before committing a sprint.
• Not a product differentiator. The low opportunity score (35.3) is the right read — this is commodity developer tooling with indirect user impact. It should never appear on a customer-facing roadmap; it belongs in platform/engineering-health metrics.

When to Consider This Package

Adopt when:

• We are planning a PHPUnit major-version jump (especially 9 → 10/11, which carries the heaviest BC surface) and the test suite is large enough that manual edits are a multi-sprint cost.
• Rector is already in the toolchain (or is easy to add) — this package is worthless standalone and buys us a rule set on top of an existing investment.
• Tests are conventionally structured (standard TestCase subclasses, limited custom base classes, few dynamic mock patterns) so rules match cleanly.
• We need a repeatable, reviewable migration — dry-run diffs in a PR beat a scattered series of hand edits for auditability.

Look elsewhere or skip when:

• The suite is small (a few dozen tests) — running and reviewing the tool costs more than fixing by hand.
• Framework constraints pin PHPUnit anyway (e.g., a Laravel version that doesn't yet support the target PHPUnit); automating a migration we can't ship is wasted effort.
• Tests rely on heavy metaprogramming, custom assertions, or non-standard bootstrapping — expect false positives and manual review on the riskiest code.
• The team has no Rector experience and no appetite to own a codemod step in CI; the learning cost outweighs one migration.
• We need rules for an internal framework or in-house test harness — those must be written ourselves regardless.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed automation add-on for a code-modernization tool we may already use. It converts what is normally a slow, error-prone PHPUnit upgrade into a reviewed pull request — reducing the engineering cost of staying on supported, secure PHP and Laravel versions. Cost is essentially zero (a dev-only dependency); the return is measured in upgrade days avoided and delayed security patches eliminated. It is infrastructure, not a product feature: expect no customer-visible change.

For engineering: It's the PHPUnit rule set for Rector — dry-run first, review the diff, then apply. It handles the tedious 80% of a PHPUnit 8/9 → 10/11 migration (annotations to attributes, signature and assertion changes) and leaves the judgment calls to us. Caveats: it's a small project (117 stars, no listed dependents) so we pin the version, keep the changes in a dedicated PR, and audit anything touching mocks or custom assertions. Budget roughly one engineer-day to pilot on the largest test directory and produce a scoped diff; that pilot is the go/no-go gate, not a full commitment.