Product Decisions This Supports
- Test-suite modernization sequencing. This package exists to answer a single roadmap question: do we rewrite the whole legacy test suite before we can move the runtime, or do we stage the runtime upgrade behind a compatibility layer and pay down test debt separately? It supports choosing the staged path when the test suite is the only blocker.
- Build vs. buy vs. codemod. It is a reference implementation for one option — a thin shim that re-exposes PHPUnit 5.x APIs on top of 6.x. Comparing it against a scripted migration (Rector PHPUnit rulesets, PHPUnit's own migration guide, a
@expectedException → expectException sweep) is the actual decision this package informs. In most cases the codemod wins on total cost of ownership; the shim wins only on calendar time.
- Upgrade scoping and risk budget. It lets a PM quantify "how much of our upgrade is blocked by test semantics rather than application code," and set a milestone — e.g., "runtime on PHP 7.x by Q2, shim removed by Q3" — with a visible expiration date on the workaround.
- Test debt triage. Which tests are actually load-bearing? A shim that makes old assertions silently pass can also reveal how many tests were never meaningful; it gives the team a period to measure and prune before committing to a rewrite.
- Dependency policy precedent. A 0-star, 0-dependent, self-described "hack" is a useful forcing function for a written rule: no unmaintained packages in the dependency graph; workarounds must be vendored, owned, and have a named removal ticket.
- Platform/legacy product bets. For agencies and platform teams maintaining multiple Laravel 5.x client applications, this supports a decision about a reusable internal migration toolkit versus per-client one-off fixes.
When to Consider This Package
Adopt (as a vendored fork, not a dependency) when:
- You maintain a Laravel 5.x application on PHPUnit 5.x with a large suite — hundreds of tests — written against APIs that changed in 6.x (
setUp()/tearDown() signatures without : void, @expectedException annotations, assertInternalType, getMock).
- A runtime upgrade is blocked only by mass test failures, and there is a business reason to move first: an EOL PHP version, a security patch, a hosting or compliance deadline.
- Your team has the capacity to own it — fork it into a VCS/path repository, pin the commit, read every line, and add tests around it. Upstream is not maintained and should not be relied on.
- The workaround is time-boxed and tracked: a removal ticket, a named owner, and a date. Treat it as scaffolding, not architecture.
- You accept the semantic risk: shims can make suites green without making them correct, so pair it with a coverage check on the paths you are about to ship.
Look elsewhere when:
- The application is greenfield, or already on PHPUnit 9/10/11 — this package is irrelevant. Laravel 8+ projects have no use for it whatsoever.
- You can run a codemod. Rector's PHPUnit rulesets plus the official migration guide handle the majority of 5.x → 6.x breakage mechanically and leave you with code that keeps working for years. That is the default recommendation.
- You cannot own a fork. Pulling an unmaintained 0-star package transitively into CI is supply-chain exposure with no upgrade path.
- The blocker is a small number of tests. Skipping or deleting a handful of legacy tests behind a filter, and rebuilding coverage in a new suite, is cheaper than any compatibility layer.
- You are in a regulated or audited environment where every dependency must have a maintained release process. It does not.
How to Pitch It (Stakeholders)
To executives: This is not a package we adopt as a product dependency — it is a temporary workaround for one specific problem: old test code that won't run on a newer PHPUnit. Its value is calendar time, measured in weeks, on a runtime upgrade that may be driven by security or support deadlines. Its cost is a small unmaintained component we would have to fork and own, plus the risk that a green test suite gives false confidence. My recommendation: fund a one-to-two-sprint mechanical test migration instead, and keep this in the decision record only as evidence that a staged approach was considered. If we do use it, it goes in as an internal fork with a removal date, not as a Composer dependency.
To engineering: It is a narrow compatibility layer that re-exposes PHPUnit 5.x TestCase and assertion behavior on 6.x. If we use it, we vendor it, read it, and add characterization tests around our riskiest suites before trusting the output. Plan for removal from day one; the shim is the first thing we delete after the runtime upgrade lands.
Bottom line: Reference material, not a recommendation. The strategic decision it supports — staged test migration vs. full rewrite, and who owns the workaround — is more valuable than the code itself.