Phpunit Bridge Laravel Package

Product Decisions This Supports

• Framework upgrade planning (the biggest one). The package turns "we have 400 deprecation warnings, unclear which matter" into a grouped, thresholded, actionable report. That directly informs the decision of when to schedule a Laravel major or PHP 8.x upgrade — you can sequence the work by counting real, de-duplicated deprecations rather than guessing from release notes.
• Build vs. buy for test infrastructure. Deprecation triage tooling is pure undifferentiated heavy lifting. Default position: buy/adopt (MIT, Symfony-maintained) rather than have a platform engineer spend a sprint building a custom PHPUnit listener that will rot.
• CI gating policy. The configurable deprecation thresholds make this a policy lever, not just a report: "max N direct deprecations, 0 indirect from our own code" as a merge gate. That's a concrete, low-cost mechanism to stop deprecation debt from compounding between upgrade cycles.
• Test-suite modernization sequencing. The PHPUnit compatibility layer de-risks the PHPUnit 9 → 10 → 11+ migration, because tests can run across versions while the suite is being converted. This lets you split "upgrade PHPUnit" and "upgrade framework" into two separately shippable roadmap items instead of one big-bang epic.
• Flaky/time-bomb test reduction. ClockMock/DnsMock and the time-sensitive test detection address a recurring, hard-to-attribute source of CI noise (tests that pass for months then fail on a date boundary or in a network-restricted runner). Quantifying that noise is usually the fastest way to justify the work.
• Dependency/procurement policy for dev dependencies. Because it's dev-only, it's a low-risk addition to the toolchain review — useful as a precedent when setting rules about how much non-production dependency surface the team accepts.
• Prioritizing which Symfony-component deprecations to act on. Laravel depends on Symfony components under the hood (console, http-foundation, finder, error-handler, mime), so Symfony deprecations do surface in Laravel codebases. This package is what makes those visible and attributable to your code versus vendor code.

When to Consider This Package

Adopt when:

• You are planning or mid-flight on a major upgrade (PHP minor/major, Laravel major, or a locked set of Symfony components) and need a defensible inventory of what's deprecated and where.
• Your test output is already drowning in deprecation noise and engineers have started ignoring it — the grouped reports and "direct vs. indirect" split restore signal.
• You have a large, long-lived test suite (thousands of tests) where migration and CI hygiene are recurring budget lines rather than one-off chores.
• You need cross-version PHPUnit support as a transitional state during a suite migration.
• You want a CI-enforceable deprecation budget rather than a periodic cleanup initiative.
• Your team already runs Symfony components directly (e.g., a Laravel app plus Symfony packages, or a shared internal library published as a Symfony-adjacent package).

Look elsewhere or defer when:

• Small/pure Laravel app with an already-clean suite. PHPUnit's native --display-deprecations, --fail-on-deprecation, and baseline support cover most of this. Adding a bridge for a 200-test suite is overhead without payoff.
• Pest-first team with no Symfony component exposure. Much of the value is Symfony-deprecation-specific; the fit is weaker and the mental model mismatch is real.
• You need runtime observability, not test-time. This is a dev-only dependency. It will never help you catch deprecations in production traffic; pair it with APM/log-based error tracking if that's the actual requirement.
• You need a hard support SLA or commercial backing. It's a sponsored-but-community Symfony package; treat it as best-effort OSS. The unusually long backport cadence (5.4 → 8.1 branches all receiving fixes) is a strong maintenance signal, but it isn't a contract.
• Your constraint is "minimize dependency count." This is another dev dependency to version-manage; if the team is aggressively trimming require-dev, weigh that explicitly.

Caveat worth flagging internally: the dependency/reach metrics for this package are not a reliable demand signal — it's historically a Symfony monorepo subpackage, so star counts and dependent counts understate actual usage and shouldn't be treated as adoption evidence either way. Judge it on the release cadence, backport discipline, and whether the problem it solves is on your roadmap.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is a free, MIT-licensed, actively maintained testing utility from Symfony that makes framework and PHP upgrades predictable instead of heroic. It converts "we think there's a lot of deprecated code" into a counted, grouped, prioritized list, and it lets us put a hard ceiling on new deprecation debt in CI. The business value is schedule risk reduction on upgrades we have to do anyway, plus reclaimed engineering time currently spent triaging noisy test output and date-dependent flaky tests. Cost is near zero: dev-only, no production footprint, no licensing spend.

For engineering — the ask: Add symfony/phpunit-bridge as a require-dev dependency and adopt two things first — the deprecation report in CI and the threshold gate. Do not attempt a full configuration rollout in one pass; start with reporting only, measure volume for two sprints, then set thresholds slightly above current state and ratchet down. Expect the main friction to be triaging the initial backlog, not the install. If we're also planning a PHPUnit major-version bump, sequence the bridge adoption first — its compatibility layer is what lets the PHPUnit upgrade and the framework upgrade be separate, individually shippable pieces of work rather than a single high-risk change. Success criteria: a known deprecation count that trends down sprint over sprint, zero deprecation-related surprise failures during the next upgrade, and no date- or DNS-dependent test failures in CI.

Known risks to state up front: dev-only dependency, community-supported (no SLA), and value is concentrated in Symfony-component deprecations — so if our next two quarters have no upgrade work on the roadmap, this is a "revisit later," not a "do now."