Phpstan Extension Ide Helper Laravel Package

Technical Evaluation

Architecture Fit

• What it is: A dev-only Composer package that ships generated dummy declarations for PHPStan's internal namespaces (PHPStan\... classes, functions, and constants). PHPStan is distributed as a PHAR, so IDEs cannot index its internals; this package re-materializes those symbols as plain PHP files with return; injected after each namespace declaration, making them autocomplete- and go-to-definition-friendly while remaining inert at runtime.
• Where it fits: Only repos that author PHPStan extensions — custom Rule, NodeVisitor, TypeNodeResolverExtension, or config-level extensions. In a typical Laravel codebase that merely runs PHPStan (via Larastan or a CI step), this package adds zero value; the analyser already resolves its own internals at execution time.
• Where it doesn't fit: Application runtime, queue workers, HTTP path, anything deployed. It is require-dev, produces no artifacts consumed in production, and cannot affect Laravel's container, routing, or Eloquent behaviour.
• Value proposition is DX, not correctness: The stubs inform the editor. They do not participate in analysis. Any team expecting faster or more accurate phpstan analyse runs will be disappointed — the win is reduced context-switching for engineers writing rules by hand.
• Assessment: Architecturally inert and safe, but narrow. The TPM question is not "is this risky to production" (it isn't) — it is "does our team write PHPStan extensions often enough to justify a tracked, version-coupled dev dependency."

Integration Feasibility

• Install mechanics: Single composer require --dev line; no service provider, no config publish, no Laravel package discovery registration. Integration cost is effectively a lock-file entry plus IDE configuration.
• Composer coupling (the real hazard): Per the README, the generated composer.json inherits phpstan/* dependencies discovered from phpstan-src. That means installing the helper can transitively constrain the phpstan/phpstan version your repo resolves. A helper release generated from PHPStan 2.3.x may refuse to coexist with a tree pinned to 2.2.x, or worse, silently downgrade/upgrade PHPStan. This must be verified against the helper's actual published composer.json before adoption — it is not stated in the README, and it is the single thing most likely to break CI.
• Version-pairing requirement: Stubs must match the PHAR minor. Helper 2.3.x describes PHPStan 2.3.x internals; pairing 2.3.x stubs with a 2.2.x analyser yields phantom classes and misleading signatures in autocomplete — a silent DX regression that no test will catch.
• Compatibility envelope: PHP 7.4+/8.x as inherited from PHPStan; no Laravel or framework constraint introduced. IDE support is de facto PHPStorm (native PHAR indexing) or VSCode + Intelephense with manual stub paths.
• Technical risk (ranked):
  1. Maintainer/bus factor — 9 stars, 0 dependents, effectively a single-maintainer generated-artifact project. Abandonment does not break builds; it quietly freezes you at the last generated PHPStan version.
  2. Release opacity — release notes are a bare link to phpstan-src/tree/<tag>. No changelog, no breaking-change callout. Blast radius is unassessable from the release itself; you must diff upstream.
  3. Stub fidelity — the return;-after-namespace generation is a pragmatic trick. Signatures, generics, and @template annotations survive, but behaviour does not; anyone reading a stub as if it were source will be misled.
  4. Composer constraint conflicts — as above.
  5. Supply chain — a dev dependency that pulls generated code from a third party into every developer's IDE index. Low but non-zero; mitigated by MIT license, no runtime load, and lock-file pinning.
• Key questions for the TPM:
  1. Do we author PHPStan extensions at all, or only consume them? If consumption only → reject, no further work.
  2. What PHPStan minor are we on today, and does the helper declare a compatible constraint?
  3. Does the helper's composer.json constrain phpstan/phpstan, and if so does it conflict with our pin?
  4. Are we willing to accept a dependency with one maintainer, no test suite, no changelog, and an auto-publish job running every 30 minutes?
  5. What is the fallback if it is abandoned — clone phpstan-src and add it to the IDE include path, or rely on PHPStorm's PHAR indexing?
  6. Can we pin helper and PHPStan to identical patch versions in composer.lock for deterministic team-wide stubs?

Integration Approach

Stack Fit

• Laravel/PHP: No framework interaction. Fits any Composer project on PHPStan ^2.x; requires that the repo already has PHPStan wired into CI, otherwise there is nothing to extend.
• Toolchain: Composer 2, PHPStan (PHAR), PHPStorm or VSCode + Intelephense. No optional bridges, no extension-installer interplay, no config file.
• Team profile: Pays off in monorepos or platform teams that maintain a shared static-analysis ruleset consumed by many Laravel services. Poor fit for single-app product teams with one or two bespoke rules.

Migration Path

1. Gate on need: confirm at least one engineer actively develops PHPStan extensions. Otherwise stop; document the decision and move on.
2. Recon: composer show phpstan/phpstan; inspect the helper's published composer.json for phpstan/* constraints; grep -r "PHPStan\\\\" app/ tests/ for existing FQCN references in custom rules.
3. Bump the analyser first: move phpstan/phpstan to the target minor and get a clean full analysis run before introducing stubs. Isolate analyser breakage from stub breakage — mixing the two makes triage impossible.
4. Add the helper pinned to the same patch: "headercat/phpstan-extension-ide-helper": "2.3.1" alongside "phpstan/phpstan": "2.3.1". Exact pins, not carets, so every developer's editor sees identical symbols.
5. IDE reconfiguration: PHPStorm — invalidate caches and restart so the PHAR and stubs are re-indexed. VSCode — point Intelephense at the stub directory, clear its index, restart the language server.
6. Smoke test: open a custom rule, verify go-to-definition and autocomplete resolve into PHPStan\ internals, then run phpstan analyse to confirm the analyser is unaffected.
7. Commit and communicate: one lock-file change, one short note in the engineering handbook describing the version-pairing rule.

Compatibility

• Strict pairing: helper minor == PHPStan minor. Treat the pair as a single logical dependency. A future PHPStan 3.0 will invalidate these stubs wholesale and require a coordinated bump.
• IDE matrix: PHPStorm works out of the box; VSCode requires Intelephense plus explicit stub paths and re-verification after every bump; other editors are effectively unsupported.
• Fallback: cloning phpstan-src into the IDE include path achieves the same result without a third-party dependency, at the cost of per-developer setup.

Sequencing

1. Need-gate decision (owner: TPM).
2. PHPStan minor upgrade + green analysis in CI.
3. Helper install pinned to the identical patch; lock file committed.
4. IDE cache invalidation and DX smoke test on one rule.
5. Upstream watcher for PHPStan tags (below) so the next minor does not arrive unnoticed.
6. Team-wide rollout once a single engineer has validated.

Operational Impact

Maintenance

• Cadence: The package regenerates on a 30-minute schedule and publishes per PHPStan release; expect a meaningful new version roughly whenever PHPStan ships a minor (historically several per quarter). Each one is a candidate bump for us.
• Ownership: Assign one owner (static-analysis or platform champion). The maintenance action is small but recurring: read the PHPStan release notes, bump the paired pin, re-run analysis, invalidate IDE caches.
• Detection automation: a scheduled workflow that queries the latest phpstan/phpstan release and compares it against the pinned pair, opening a tracking issue on mismatch. Detection is cheap; do not rely on human recall.

Support

• Support surface: IDE-specific, not runtime. Expect recurring "autocomplete is broken" tickets resolvable by cache invalidation or a language-server restart. Document this once in the runbook.
• Onboarding: new engineers get it automatically via composer install but will not know why the stubs exist. A one-paragraph README in the repo explaining the pairing rule prevents accidental version drift during routine dependency bumps.
• Vendor relationship: none. No SLA, no maintainer contract, no security disclosure process. Accept that support is best-effort community.

Scaling

• Horizontal: trivially scalable — it is a per-repo dev dependency with no shared service, no runtime surface, no capacity implications.
• Breadth: scales poorly as organizational standardization. If 20 Laravel services each need it, each must pin the paired versions independently; without a shared base composer.json or Renovate/Dependabot group rule, drift is inevitable.
• Recommended governance: a grouped dependency-update rule that bumps PHPStan and this helper together, plus a Renovate/Dependabot grouping key. This is the single highest-leverage operational control.

Failure Modes

• Version skew (most likely): helper stubs describe a different PHAR than the one running. Symptom: autocomplete suggests classes that do not exist, or misses ones that do. Impact: developer confusion and mis-typed annotations; no build failure. Detection requires an explicit pairing check.
• Composer constraint conflict: helper's inherited phpstan/* requirements clash with the repo pin, blocking composer update or silently mutating the analyser version. Impact: CI breakage, resolvable but disruptive. Verify constraints before adoption.
• Abandonment: upstream stops publishing. Impact: stubs freeze at the last PHPStan version; autocomplete degrades gradually as PHPStan evolves. No production risk, no urgent action; fallback is cloning phpstan-src.
• IDE index poisoning: stale and duplicate symbols after an upgrade without cache invalidation. Impact: phantom errors in the editor that do not appear in CI — the classic "works in the pipeline, red in my IDE" complaint.
• False confidence: engineer trusts stubs as source and writes rules against a signature that has drifted. Mitigated only by disciplined phpstan analyse runs and code review.

Ramp-Up

• Effort: under an hour for a single engineer to install, configure the IDE, and validate on one rule. Near-zero learning curve — the package has no API, only file presence.
• Friction: concentrated in IDE configuration (particularly VSCode/Intelephense stub paths) and in understanding the pairing constraint. Both are one-time and documentable.
• Recommendation: adopt opportunistically — only if the team already writes PHPStan extensions and can commit to paired pinning plus a grouped update rule. Otherwise, decline: the DX benefit is real but narrow, and the coupling to a low-signal single-maintainer package is not worth carrying for teams that merely run PHPStan.