Phpstan Extension Ide Helper Laravel Package

Product Decisions This Supports

• Whether to invest in custom static analysis at all. This package only matters if the roadmap includes writing bespoke PHPStan rules/extensions (domain invariants, architectural guardrails, framework-specific footguns). It is a leading indicator that a team has graduated from "run PHPStan at level 8" to "encode our business rules as analyser rules" — a meaningful capability investment. Approving adoption is implicitly approving that roadmap item.
• Developer-experience budget allocation. Autocomplete and go-to-definition inside PHPStan internals is pure DX. If a PM is weighing "spend two sprints on rule authoring" against "keep shipping features," this dependency lowers the per-rule cost of authorship and shortens onboarding for engineers who have never written a rule before. It converts a niche skill into a normal one.
• Build vs. buy for internal tooling. The alternative to this package is an engineer cloning phpstan-src into the repo and hand-wiring include paths — a one-off, undocumented, person-dependent hack. Adopting a published (MIT) helper is the "buy" side of build-vs-buy at near-zero price, and it removes a recurring excuse not to write rules.
• Standardization decisions. Choosing this effectively picks a side on team tooling: it works cleanly in PhpStorm, needs manual Intelephense configuration in VS Code. That is a real input into "do we standardize on one IDE / one static-analysis workflow?" and into the IDE licensing line of the engineering budget.
• Toolchain upgrade sequencing. Because the helper's version must track PHPStan's minor version, it forces (and makes visible) a decision the team would otherwise defer: "are we on PHPStan 2.3, and who owns that bump?" It gives the PM a concrete, low-stakes trigger to schedule framework/tooling maintenance rather than letting pins rot.
• Prioritizing CI hygiene as a product-quality lever. The stubs are declaration-only — they inform the editor, not the analyser. That asymmetry is a useful governance talking point: it reinforces that green local autocomplete is not evidence of correctness, and that the CI phpstan analyse gate is the real quality mechanism worth funding.
• Non-decision for most roadmaps. If the product org has no custom-rule backlog, this package is not a lever at all; it should be recorded as "no action" rather than smuggled in as a best practice.

When to Consider This Package

Adopt when all of the following hold:

• The team is actively authoring PHPStan extensions or custom rules — not merely consuming third-party rule sets or tuning levels in phpstan.neon.
• PHPStan is pinned to a specific minor and the team can commit to keeping the helper on the same minor (helper 2.3.x ↔ PHPStan 2.3.x). Mismatched minors produce stubs describing symbols the analyser does not have, which is worse than no stubs.
• The primary IDE is PhpStorm, or the team has the appetite to maintain explicit Intelephense/stub-path configuration in VS Code and re-verify it after each bump.
• There is at least one engineer who will own the upgrade cadence and a CI job that runs the analyser, so the "stubs vs analyser" gap is caught mechanically.
• The custom-rule surface is large enough or long-lived enough that repeated PHAR-introspection friction is a recurring tax, not a one-off.

Look elsewhere — or explicitly decline — when:

• No custom rules are planned. Standard PHPStan usage needs nothing from this package.
• The ruleset is one or two files. Cloning phpstan-src locally, or relying on whatever stubs the IDE/PHPStan tooling already ships, is cheaper than adding a dependency with a per-minor upgrade obligation.
• The team spans multiple PHPStan minors across repos, or cannot yet move off 2.2.x. Confirm the older helper line is still installable before committing; if the maintainer supersedes rather than branches, adoption becomes a forced upgrade path.
• Supplier risk is unacceptable. Nine stars, zero dependents, single maintainer, releases generated by an automated 30-minute job with release notes that are a bare link to the upstream tag. That is fine for a dev-only convenience; it is not fine if the org requires a supported vendor, a security review trail, or a changelog it can audit. Mitigate by accepting that every helper release must be treated as potentially breaking and gated behind a CI run.
• PHPStan 3.0 is on the near horizon for the team. Stubs will break wholesale; defer until the ecosystem settles.

How to Pitch It (Stakeholders)

For executives (30 seconds). We are considering a small, MIT-licensed, dev-only package that makes our static-analysis tooling nicer to work with. It ships nothing to production, adds no runtime dependency, and costs nothing. Its only job is to let engineers' editors understand the internals of PHPStan — the analyser we already run — so that when we encode our own code-quality rules, engineers can write them quickly instead of fighting their IDE. The trade-off is a small recurring maintenance item: it must be upgraded in lockstep with PHPStan, roughly whenever PHPStan ships a minor release. Recommendation framing: approve only as part of a decision to actually write custom rules; if that work is not on the roadmap, decline and revisit later.

For engineering leads. This removes a known friction point: PHPStan ships as a PHAR, so IDEs cannot resolve its internal classes, which is exactly what you need when authoring custom rules and nodes. The package publishes generated dummy stubs for those internal namespaces. Practical consequences you should plan for:

• Pin the pair. Keep headercat/phpstan-extension-ide-helper and phpstan/phpstan on the same minor, ideally the same exact patch in the lock file, so every developer resolves identical stubs.
• Upgrade PHPStan first, helper second. Isolate analyser breakage from stub breakage; get a green analyse run before touching the helper.
• Invalidate IDE caches after every bump (PhpStorm: invalidate and restart; VS Code: re-point Intelephense and clear its index). Stale caches are the most likely source of phantom-symbol confusion.
• Never trust the stubs for correctness. They are declaration-only. The CI analyser run is the gate; autocomplete is a convenience.
• Automate the watch. Put a scheduled workflow on upstream PHPStan releases that opens a dependency-bump ticket, rather than relying on someone noticing. Treat each helper release as potentially breaking — the release notes carry no changelog.

Honest risk statement to include in the pitch. This is a single-maintainer package with negligible adoption. Its value is real but narrow, and it is only worth the upgrade obligation if we are genuinely authoring rules. If we are not, the correct answer is no action — and if we are, the correct answer is to adopt it with a named owner, a paired pin, and an automated upstream watcher.