Php Assumptions Laravel Package

Product Decisions This Supports

• Technical-debt prioritization. The tool reports where code silently assumes things it never checks — a value is non-null, an array key exists, a call returns an object of a given shape, a variable is defined. Assumption density per file/module is a usable proxy for fragility, so it helps rank modules for hardening work instead of guessing.
• Scoping a typing/strictness initiative. If the roadmap includes declare(strict_types=1), native parameter/return types, or a PHPStan/Psalm level increase, this gives a cheap pre-read on how much implicit contract exists in the codebase and where the payoff concentrates.
• Build vs. buy for static analysis. It is a focused, MIT-licensed dev dependency built on nikic/php-parser. That makes it a low-cost "buy" for one specific lens rather than a reason to build custom AST tooling in-house.
• Where to add runtime guards vs. type declarations. Assumptions flagged in boundary code (controllers, console commands, integrators of third-party SDKs) argue for validation/guards; assumptions in internal service code argue for type declarations and PHPStan rules.
• Migration risk assessment (PHP 7.x → 8.x, framework upgrades). Assumption-heavy code is where upgrade breakage tends to surface. Useful input when estimating upgrade effort or deciding whether to refactor-before-upgrade vs. upgrade-then-fix.
• Onboarding and code-review standards. A concrete artifact to point at when setting expectations ("don't add assumptions you can't enforce") and when explaining why a PR wants a null check or a narrowed type.
• Vendor/third-party confidence checks. Running it over code you're about to acquire, fork, or inherit gives a fast read on how defensive that code actually is.

When to Consider This Package

Consider it when:

• You own a legacy or inherited PHP codebase with sparse type declarations and want a quick, low-effort signal on implicit contracts before committing to a hardening roadmap.
• You already run PHPStan/Psalm and want an additional, complementary lens specifically about unchecked assumptions rather than type errors.
• You need a one-off audit artifact for a planning discussion — a report you can hand to engineering to size work.
• You want something cheap to trial: dev dependency, MIT license, actively released (last release March 2025), no runtime footprint.
• You have engineering appetite to interpret results. This is informational output, not a gate.

Look elsewhere when:

• The codebase is greenfield and fully typed — output will be sparse and the tool adds little over existing analysis.
• You need CI enforcement, precise diagnostics, or autofixes. PHPStan/Psalm (with strict rules) and Rector are the mature choices; this tool doesn't replace them and shouldn't be a merge gate.
• You want vendor support, SLAs, or a large community. 164 stars and an unspecified repository is a thin diligence surface — assume bus-factor risk and pin versions.
• Your team has no spare tooling capacity. Each added analyzer costs onboarding, CI time, and triage; this one has the worst ratio of noise-to-signal among the mature options if you're already at PHPStan level 6+.
• The stack isn't PHP, or you need analysis of runtime/dynamic behavior (feature flags, DI container graphs) rather than static source assumptions.

Diligence before adoption: confirm PHP version support against your matrix, confirm output format (human-readable vs. machine-parseable — matters if you want to trend the metric over time), and run it on a representative module to gauge false-positive volume.

How to Pitch It (Stakeholders)

For executives: A free, low-risk developer tool that measures how much our PHP code relies on unverified assumptions — the kind that turn into production incidents during upgrades and refactors. It costs a dev-dependency and an afternoon; in exchange we get a ranked list of where fragility concentrates, which lets us aim hardening budget at the modules that actually carry risk instead of spreading effort evenly. It is a diagnostic, not a silver bullet, and it does not replace our existing static analysis.

For engineering leads: One more lens on code quality, complementary to PHPStan/Psalm rather than competing with them. It surfaces unchecked nulls, array keys, return shapes, and undefined variables — the assumptions that static analysis at your current level may not yet encode. Run it over a target directory, read the report, and use it to decide where to tighten types, add guards, or raise the PHPStan baseline. Treat it as advisory: do not gate CI on it, pin the version, and expect to spend time triaging output before you trust any trend.

For the team doing the work: It's a read-only analyzer — no runtime impact, no code changes, no lock-in. If the signal is weak, we drop it; the cost of finding out is roughly one sprint task.