Generator Laravel Package

Technical Evaluation

Architecture fit. php-stubs/generator is a dev-time code generation tool, not a runtime library. It parses PHP source with nikic/php-parser and emits declaration-only stubs (functions, classes, traits, interfaces, constants, documented/undocumented globals). That places it firmly in the build/developer-tooling lane of a Laravel codebase — it should never appear in require or on a request path. The most defensible fit is as a normalization layer for code we don't control or can't type: legacy modules, vendored third-party packages, internal libraries published without PHPDoc, and WordPress-style mixed declarations-and-side-effects files. Its distinguishing technical property is that it works purely statically — no autoloading, no instantiation, no execution — so it can stub code that a reflection-based tool (e.g., laravel-ide-helper model/facade generation) cannot load safely. That is the single strongest argument for adoption, and the one a TPM should lead with.

Integration feasibility. Straightforward. Composer install as --dev, PHP 7.4+ (aligned with a Laravel 9+ runtime), PHP-Parser v5 support since 0.8.5, and a two-line programmatic API (StubsGenerator + Finder + Result::prettyPrint()) alongside the generate-stubs binary. Integration work is not in wiring — it is in distribution and gating: deciding whether stubs are committed artifacts or CI-generated, and registering them with PHPStan (stubFiles / scanFiles) or Psalm so they actually influence analysis. Expect the real effort to be in configuring the analyzers around stub-inherited false positives, not in the generator itself.

Technical risk. Ranked:

Key questions before committing.

1. What is the actual target — legacy in-house code, a specific vendored package, or general onboarding DX? The answer changes whether this is a one-off script or a maintained pipeline.
2. Which analyzer is the consumer — PHPStan, Psalm, or IDE-only? IDE-only is a much cheaper commitment and avoids the false-positive tuning work.
3. Will generated stubs be committed to VCS or produced per-CI-run? (Commit = reviewable drift, CI = guaranteed freshness; pick one and state it as policy.)
4. Who owns regeneration, and what triggers it — dependency bump, release tag, or scheduled job?
5. Do we already run laravel-ide-helper? If so, scope this tool strictly to non-Laravel/vendor code to avoid two competing stub sources for the same symbols.
6. What is the success metric — measured reduction in IDE "undefined method" warnings, PHPStan baseline shrink, or onboarding time? Without a baseline, this becomes unfalsifiable tooling debt.

Integration Approach

Stack fit. Clean for Laravel + Composer + PSR-4. It is a CLI/dev dependency with no framework coupling and no ServiceProvider — deliberately framework-agnostic, which is appropriate: it should sit in require-dev and a Composer script, not in the application's service container. Consumers are the IDE index, PHPStan/Psalm, and optionally a PHPUnit assertion over generated output.

Migration path. There is no migration — it is additive and removable. Nothing at runtime references the stubs. The practical path is: add as dev dependency → point Finder::create()->in(...) (or the CLI with --out) at one legacy package → commit or artifact the output → register it with one analyzer → measure. Rollback is deleting a file and a config entry. This is a genuinely low-regret adoption decision; the cost is ongoing maintenance, not reversibility.

Compatibility. Confirm PHP-Parser v5 alignment with any other tooling in the graph (PHPStan bundles its own parser and does not conflict). Verify generated stubs against the Laravel version in use — a stub file generated from a package version we no longer ship is worse than no stub. Flag the pre-1.0 version line: pin to a minor (^0.8) and treat minor bumps as review-worthy, given the changelog pattern of behavior-affecting fixes.

Sequencing.

1. Pilot (1 sprint). One legacy or vendor target, IDE-only consumption, no analyzer changes. Cheap, visible, reversible.
2. Baseline measurement. Record IDE diagnostics and PHPStan error count on that target before/after. Gate stage 3 on a real delta.
3. Analyzer integration. Register stubs with PHPStan stubFiles; triage false positives into ignoreErrors with justifications, not blanket silencing.
4. Automation. Composer script (composer stubs) plus a CI job that regenerates and fails on diff, making drift a build failure rather than a discovery.
5. Scoped rollout. Extend to additional targets only where step 2's metric repeated. Resist repo-wide generation — output volume grows and reviewability collapses.

Explicitly out of sequence: applying this to Laravel framework internals or generated code. Those are already covered by bundled IDE stubs; generating our own creates competing definitions.

Operational Impact

Maintenance. The ongoing cost is drift management, not tool maintenance. Budget for: a regeneration trigger tied to dependency bumps, a committed stub file (or CI diff check), and an owner for the ignore-list that will inevitably accrue. The generator's own release cadence is modest but responsive; assume you may need to fork or pin if PHP syntax support lags a framework upgrade — that is the fork-and-forget contingency to note in the ADR.

Support. No commercial support; community issues only, small maintainer pool. Internal support burden is low for CLI usage and moderate once stubs feed a static analyzer, because "PHPStan is now complaining about a stub" becomes an in-team ticket. Assign a single owner (platform/DX engineer) rather than distributing it across teams.

Scaling. Generation is linear in parsed bytes and memory-bound on very large trees. For a monorepo, generate per-package rather than monolithically — smaller outputs, clearer ownership, incremental CI. Static-analysis time will grow with stub volume, so watch PHPStan wall-clock as a secondary metric; if it regresses, narrow stubFiles to the packages that demonstrably benefit.

Failure modes to instrument.

• Silent drift — stubs frozen at an old signature; analyzer validates against a lie. Mitigation: CI diff check.
• Parser hard-fail on new syntax — generation aborts after a PHP upgrade. Mitigation: pin, test in CI on the target PHP matrix.
• False-positive cascade — stub-induced analyzer errors erode trust and get blanket-ignored. Mitigation: per-error justification; treat ignore-list growth as a signal to withdraw a target.
• Duplicate/conflicting symbols — two stub sources (this tool + laravel-ide-helper + PHPStan's own) for one symbol. Mitigation: strict, documented source-of-truth rule per symbol class.
• Overreach — applied to typed modern code, adding maintenance for near-zero gain. Mitigation: adoption criteria = untyped or vendored only.

Ramp-up. Low for engineers (two commands), moderate for the team's process (stub location, regeneration trigger, analyzer config ownership). Realistically half a day to first working output, one to two sprints to a trustworthy automated pipeline. The trap is treating ramp-up as the hard part: the tool is easy, the policy around generated artifacts is the actual deliverable.

TPM recommendation. Adopt as a scoped dev-tooling pilot on untyped/vendored code, gated on a measured IDE-or-analyzer delta and paired with a CI drift check. Do not adopt as a general type-safety initiative, and do not position it as covering Laravel's dynamic surfaces. Publish the adoption criteria and the regeneration trigger before the first commit, or this quietly becomes unowned generated code — which is exactly the debt it was meant to reduce.