Phpstan Safe Rule Laravel Package

Product Decisions This Supports

• Turning an error-handling convention into an enforceable gate. "Never trust false from file_get_contents, json_decode, or preg_match" is a code-review opinion until a rule fails the build. This package makes the convention a checkable definition of done, which is what you actually need to commit to roadmap goals like "reduce incidents in import/sync/export paths" or "harden the payment and file-processing surfaces."
• Deciding whether to adopt thecodingmachine/safe at all. These are one decision, not two. Safe alone is an optional wrapper developers skip under deadline; paired with this rule, any un-wrapped call surfaces in CI. If Safe is on the table, budget them together — or reject both together.
• Build vs. buy, resolved cheaply. The alternative is an in-house PHPStan rule plus the type-inference extensions this package already ships (json_decode return types, preg_replace_callback inference, typed preg_match $matches, JSON_THROW_ON_ERROR and first-class-callable handling). Buying costs a dev-only Composer entry; the codebase is small enough that forking remains a real fallback, which caps the downside.
• Sequencing legacy migration with real numbers. Adoption produces a countable backlog — "N unsafe call sites in the checkout service, M in the nightly reporting jobs" — which supports decisions like "gate new code now, burn legacy down via baseline across two sprints" instead of an all-or-nothing rewrite.
• Concrete feature surfaces worth naming in Laravel work: raw PHP file/URL reads inside jobs and console commands, JSON parsing without JSON_THROW_ON_ERROR in API-client and webhook glue, regex calls whose false return silently degrades matching logic, and new DateTime/new DateTimeImmutable construction (detected since v1.0) in date-heavy reporting code.

When to Consider This Package

• Adopt when all of the following hold: you are on PHP 8.1+ and PHPStan 2.x (v1.4 dropped PHPStan 1.x support), your team has adopted or is genuinely committed to thecodingmachine/safe, error-handling correctness has measurable business cost in your domain, and PHPStan already runs in CI with an owner for triaging new findings.
• Bring it in incrementally. For an existing Laravel codebase the only realistic path is a baseline or ignore-set for legacy directories, enforcing the rule on changed files and new modules first.
• Look elsewhere if: you do not use Safe — this package only redirects calls to Safe\* variants and adds nothing standalone; you are pinned to PHPStan 1.x; Psalm is your primary analyzer; or your error-handling strategy is a Result/Either type or domain-specific exceptions rather than thrown exceptions from core functions.
• Diligence flags, not blockers: modest community signal (63 stars, zero dependents) and a thin maintainer profile. Pin the version, keep the fork-in-a-day fallback, and don't make it load-bearing for anything you can't replace quickly. Also verify load order — extension.neon must be included after the base config, or a silent no-op gives false confidence that the gate is live.
• Expect some false positives around first-class callables, variadics, and cases where null is logically impossible. Budget an owner for suppression hygiene, or the rule gets muted wholesale and delivers zero value.

How to Pitch It (Stakeholders)

• Executives: "A small, dev-only addition to the static analysis we already run. It automatically flags the PHP calls that signal failure by returning false — file reads, JSON parsing, regex matching — and are the ones most often silently ignored. That class of bug shows up as corrupted imports, half-written exports, and confusing 500s rather than clean errors. Cost is roughly a few engineering days including triage; runtime overhead is zero; nothing ships to production. Success looks like unsafe-call count trending to zero in the affected paths and fewer incident tickets in file and JSON handling."
• Engineering: "Add thecodingmachine/phpstan-safe-rule as a dev dependency, include its extension.neon in phpstan.neon, and keep running PHPStan as before — it flags unsafe core calls and points at the Safe\* equivalent, and it already understands JSON_THROW_ON_ERROR (including named arguments), typed preg_match matches, json_decode return types, and first-class callables. It plays fine alongside Larastan. Constraints: PHP 8.1+, PHPStan 2.x, and it only makes sense if we're also taking the safe package. Roll out behind a baseline so we gate new code first, pin the version, and name one owner for triaging findings and suppressions so the rule doesn't get muted into irrelevance."