Phpstan Warroom Rules Laravel Package

Product Decisions This Supports

• CI quality-gate policy per territory. Adopting ^0.11 converts a documented data-corruption class into blocking build errors. The PM decides whether this rule set is a merge gate, a warn-only stage, or a periodic fleet scan — and that choice determines how much remediation work lands in sprint scope.
• Build vs. buy for static analysis. These rules encode org-specific invariants (first-party narrowing-helper contracts, encrypted-cast credential derivation) that generic PHPStan/Larastan rulesets do not cover. This release is evidence for continuing to fund an in-house rule library rather than assuming off-the-shelf tooling closes the gap.
• Roadmap sequencing and capacity. Exposure is quantified: 8 hits in emmie (all in FormatLogbookEntriesAction, one a date-of-birth shape), 6 in lokalekeuze (3 likely the documented residual false positive), 0 in the other ten territories. This sizes the pin-bump PRs and lets the PM order adoption by blast radius — write/delete paths first.
• Risk prioritization against real incidents. The seed (tc-api PR #360) is concrete: ?? '' seeded [''], read as non-empty, and unlocked a forceDelete() wipe; a gender persisted as an empty SET; a missing node parsed as now() and written as a birth date. This justifies prioritizing data-integrity rules over style/lint work in the roadmap.
• Adoption model decision. Pre-1.0 caret convention means a minor auto-adopts nobody — each territory opts in via its own pin bump. The PM chooses opt-in order and whether adoption is mandatory-by-date or opportunistic.
• False-positive budget and escape-hatch policy. ADR-0021 posture (false negatives acceptable, false positives are not) is backed by two concrete levers: inline @phpstan-ignore naming the identifier, and narrowing narrowingHelperNamespacePrefixes. The PM sets the policy for when each is acceptable vs. when the rule needs fixing.
• Coverage-gap funding decisions. The release is explicit about deliberate misses — non-literal fallbacks, helpers laundered through variables, and null-swallowing sinks (the DOB bug is motivation but out of scope). That is a roadmap input: if those shapes matter, the next investment is sink-aware/data-flow analysis, not a wider matcher.
• Acceptance criteria for "green." A clean run on a consumer with no encrypted cast is not evidence until a planted credential-keyed cache has been seen to fire. The PM can require positive-control verification as part of rollout sign-off, not just a passing pipeline.

When to Consider This Package

• You operate a fleet of Laravel/PHP services with first-party boundary/import helpers that take mixed external data and return nullable scalars — the sentinel-fallback rule is aimed exactly at that shape.
• You use Eloquent encrypted casts and derive cache keys from model attributes — the credential-derived cache-key rule applies, and its silence is meaningful only if you've validated it fires.
• You want a shared, versioned invariant library across many repos with independent adoption — the 0.x pin-bump model matches that org shape.
• You can absorb new blocking errors on a minor bump. ^0.10 excludes 0.11, but within a territory a pin bump is consumer-impacting and will surface new failures in already-clean code.

Look elsewhere or defer when:

• Single application with no fleet, no configurable first-party helper namespace (App default), and no encrypted casts — most of the value is unreachable.
• You require sink-aware or data-flow analysis. This release explicitly cannot catch a preserved null that a downstream callee swallows; that is a different tool/roadmap item.
• You cannot tolerate any false positives without inline suppressions. The known residual (a lookup helper with a required mixed key returning a nullable scalar is indistinguishable by signature) will require ignores or a namespace carve-out.
• You cannot staff the remediation or the positive-control validation. Adopting without verifying that a clean run is real converts a safety gate into a false sense of security.

How to Pitch It (Stakeholders)

For executives: this release closes a proven data-loss class, not a hypothetical one. In a single PR, an empty-string fallback on a failed parse created a "non-empty" value that unlocked a forceDelete() wipe, wrote a blank gender, and wrote today's date as a birth date. The new rule turns that silent failure into a build error at the exact line where the unreadable input is discarded. Rollout is opt-in per repo — nothing auto-upgrades — and measured exposure is 14 findings across 2 of 12 services, already triaged. Cost is bounded; the alternative is more incidents of the same shape.

For engineering: bump to ^0.11 and expect new errors from three sources: ForbidSentinelFallbackOnNarrowingHelperRule, ForbidCredentialDerivedCacheKeyRule, and a widened ForbidCredentialCastBypassRule (now reads encrypting class casts and parent::casts() in override order). Grep one identifier: forbidSentinelFallbackOnNarrowingHelper.sentinelFallback. Remediate each hit one of three ways — skip the write, fail closed (throw), or handle null explicitly and pass it on. Detection is shape-keyed, not helper-name-keyed, so renaming a helper does not silently drop coverage. The one known false-positive shape (lookup helpers with a required mixed key) has a documented inline ignore, and namespaces outside narrowingHelperNamespacePrefixes are out of scope by construction. Verify a clean run with a planted violation before treating it as evidence.