Php Compatibility Laravel Package

Product Decisions This Supports

• PHP upgrade roadmap sequencing. Running the sniffs against a target testVersion (e.g. 8.2-8.4) produces a per-file, per-sniff count of incompatibilities. That count is the cheapest available proxy for effort: use it to decide whether a PHP 8.2→8.4 jump is a single sprint or an epic, and to order which services/modules get upgraded first.
• Build vs buy for upgrade tooling. The alternative is writing bespoke regex/grep checks or paying for a commercial scanning product. This package is a maintained, community-backed rule set for PHP_CodeSniffer; the "buy" decision is effectively free, and the "build" decision reduces to configuration and triage policy rather than authoring rules.
• Scope negotiation with stakeholders. Error counts broken down by sniff category (removed functions, deprecated syntax, parameter changes, E_STRICT-era issues) let you show why an upgrade is expensive — usually a small number of files carrying most of the debt — and defend a phased release rather than a big-bang cutover.
• Support-matrix decisions. If you publish a Laravel package or SDK, this feeds the decision of which PHP versions you officially support, and it becomes a CI gate that prevents a contributor from silently raising the effective floor (nullsafe operators, enums, readonly properties, typed constants).
• Due diligence and legacy intake. For acquisitions, vendor code, or a monolith you inherited, a single scan produces a defensible "cost to modernize" input for the business case before any engineering commits to a number.
• Definition-of-Done and CI policy. Adopting it turns "don't break PHP compatibility" from a review-comment convention into an automated, blocking check — a process decision with measurable effect on regression rate.
• Deprecation watch as a roadmap input. The rule set tracks upstream PHP deprecations ahead of the runtime, so scans surface future breakage (PHP 8.4/8.5 deprecations) while there is still time to schedule the fix, rather than discovering it during a security-driven forced upgrade.

When to Consider This Package

Adopt it when any of the following is true:

• You are planning or currently executing a PHP minor or major upgrade, and need a quantified inventory of incompatible code before committing dates.
• The codebase is large, long-lived, or partly inherited, and no one can confidently state its minimum supported PHP version.
• You maintain a library/package on Packagist with a declared PHP constraint that must actually hold for consumers.
• You already run PHP_CodeSniffer (or are willing to), so the marginal integration cost is one ruleset file plus a CI step.
• You need a license-clean, no-runtime-dependency, dev-only tool — the check never ships to production and imposes zero runtime cost or attack surface.

Look elsewhere, or supplement, when:

• You need fixes, not findings. The sniffs are diagnostic; phpcbf auto-fixes only a small subset. Pair with an automated refactoring tool (e.g. Rector) for the remediation workstream, and budget triage time for false positives and for issues that require design judgment rather than substitution.
• The risk is framework-level, not language-level. Laravel's own deprecations, facade changes, and package compatibility are out of scope; use the framework's upgrade guide and your dependency manager's constraint solver.
• You need behavioural correctness, not syntax compatibility. Deeper static analysis (PHPStan/Psalm) and integration tests cover type and logic risk this package cannot see.
• Your PHP floor is fixed and contractual. If you control the runtime end-to-end and never move, the ongoing value is limited to deprecation early-warning.
• Licensing posture is restrictive. It is LGPL-3.0. As a dev-only tool that is not linked into or distributed with your product this is normally fine, but confirm with legal if you redistribute your development toolchain or vendor a modified fork.
• Package identity caveat. The wimg/php-compatibility name is the legacy/deprecated identifier; current development lives under phpcompatibility/php-compatibility (the same project, renamed). Treat the low dependent count as a signal of that rename, not of abandonment, and require the maintained package name and a recent release before adoption. Also pin your PHP_CodeSniffer major version — sniff behaviour and configuration syntax shift across PHPCS releases.

How to Pitch It (Stakeholders)

For executives: This is a free, low-risk instrument that converts "we think the PHP upgrade will take a while" into a measured number. It scans the code without running it, produces a count of incompatibilities per target PHP version, and runs automatically on every pull request thereafter. Cost is engineering hours for setup and triage — no licence fee, no runtime impact, no customer-facing change. The value is forecast accuracy on a recurring, unavoidable maintenance cost, plus a guardrail that stops the debt from silently regrowing. It is diagnostic only: it tells us the size of the job, not how to do it, so it should be paired with an automated remediation tool and the framework's upgrade guide in the same workstream.

For engineering: Add it as a dev dependency, point PHP_CodeSniffer at the PHPCompatibility standard, set testVersion to your current-and-target range, and run it in CI. Start in report-only mode, baseline the existing violations so the gate blocks new debt rather than the historical backlog, then burn the baseline down as part of the upgrade epic. Treat the output as a triage queue, not a task list — expect false positives, and route the fixable majority through an automated refactorer with tests as the safety net. It is a static check, so it complements — never replaces — your test suite, static analyser, and framework upgrade notes.