Phpstan Deprecation Rules Laravel Package

Product Decisions This Supports

• Framework and dependency upgrade planning. This is the cheapest available instrument for answering "how much of our code is sitting on APIs the vendor already intends to remove?" Every PHPStan/PHP upgrade cycle (Laravel majors, Symfony, PHP 8.x runtimes) turns into a scoping exercise: enable the rules, run analysis, and you get a countable inventory of deprecated class, method, property, constant, and trait usage. That inventory is what turns "we think we're a year behind" into a roadmap line item with a size attached.
• Build vs. buy. The alternative is bespoke tooling: grep-based searches for @deprecated docblocks, custom PHP_CodeSniffer sniffs, or manual dependency audits. All of them are worse — they don't understand inheritance, aliasing, or type resolution, and they rot. This is a maintained, MIT-licensed extension from the PHPStan organization that composes directly into the analyzer the team already runs. Buying (adopting) is clearly correct here; there is no defensible build case.
• CI gating policy. The package lets you decide, per-repository, whether deprecation usage is a warning or a hard failure. A pragmatic posture: warn on @deprecated symbols from vendor packages (you can't fix them today), fail on deprecations originating in our own code, so we never add new coupling to APIs we've already announced we're removing. That is a policy decision the PM can own, backed by a mechanical check rather than reviewer diligence.
• Technical-debt budget allocation. Because the rules run as a dev-only static analysis step with no runtime footprint, the cost of trying it is a Composer line and a NEON include. That means we can pilot on one bounded service, get a deprecation count, and use that number to argue for (or against) remediation capacity in the next planning cycle — before committing engineering time.
• Defining the "safe to migrate" boundary. The DeprecatedScopeResolver extension point lets us codify intent rather than suppress noise: tests tagged @group legacy, or adapter/anti-corruption layers that intentionally call deprecated APIs, can be excluded from reports. This matters because a rule set that cries wolf gets disabled; one that reflects our architecture gets kept.
• Vendor-code visibility. Stub files let us declare deprecations for third-party code we don't control, which is directly relevant when a Laravel or transitive dependency starts soft-deprecating an API before we're ready to move off it.

When to Consider This Package

Adopt it when:

• The repository already runs PHPStan (or will as part of the same initiative). This is an add-on, not a standalone tool — it has no value without the base analyzer, and it inherits PHPStan's configuration, baseline, and CI integration for free.
• You are on, or approaching, a major framework or PHP runtime upgrade and need a defensible estimate of surface area before committing to a migration.
• You have internal deprecation hygiene: your own code marks things @deprecated and you want to enforce that new call sites don't appear. This is the highest-value, lowest-effort use case, and it doesn't depend on anyone else's release cadence.
• Your team's review culture is inconsistent about catching deprecated usage, and you want a mechanical gate rather than reviewer memory.

Look elsewhere or defer when:

• PHPStan is absent from the stack. Introducing static analysis and this ruleset simultaneously means the deprecation noise gets conflated with baseline type errors — sequence PHPStan first, adopt this once analysis is clean or baselined.
• The PHPStan baseline is already large and unaddressed. This package will add warnings that nobody intends to action, which is the fastest way to train a team to ignore output. Pay down or baseline existing findings first.
• You need runtime guarantees. This is compile-time analysis of reachable code paths; it does not catch dynamic calls ($class::$method, string-built method names, container-resolved calls, Laravel facades resolving indirectly). It is a planning tool, not a runtime deprecation logger. If the goal is "know what actually executes in production," you want E_DEPRECATED capture from logs, not this.
• The dependency footprint matters. Note the thin external adoption signal (0 listed dependents) — in practice it ships as a de-facto companion to PHPStan and is used widely, but it means we should not assume third-party support contracts or a large troubleshooting corpus. The risk is low (dev dependency, MIT, active releases, PHPStan-org stewardship) but it is a real single-maintainer dependency for a critical-path CI check.

How to Pitch It (Stakeholders)

One-liner for executives: We can measure our exposure to deprecated APIs across the codebase in a day, for the cost of a dev dependency and a few lines of CI config — turning "how big is this upgrade?" from an opinion into a number.

For engineering: This is phpstan/phpstan-deprecation-rules, a ruleset extension for PHPStan. Install as a dev dependency; with phpstan/extension-installer it registers itself, otherwise one NEON include. It reports any reference to a class, method, property, constant, or trait annotated @deprecated, and it's smart about intent: code that is itself deprecated isn't flagged, and we can define custom "deliberately uses deprecated things" scopes (e.g. @group legacy tests, adapter layers) so the output stays signal. Stub files cover vendor code we don't own; custom attributes are supported via extension if we standardize our own deprecation marker.

Why it's low-risk: dev-only — zero production runtime surface, no autoloaded code paths, no data or security implications. MIT licensed, maintained under the PHPStan org, current releases with PHP 8.5 CI coverage, and it tracks PHPStan's own restricted-usage infrastructure, so it's structurally aligned with where the ecosystem is going rather than a bolt-on.

Honest caveats to state up front: it only sees statically reachable calls, so dynamic dispatch, container resolution, and facade indirection will escape it — pair it with runtime deprecation logging for the full picture. And its output is only as useful as our discipline in acting on it; a large unremediated warning count is worse than no check at all. Recommend a bounded pilot on one service, measure the finding count, then decide on a gating policy.