Larastan Laravel Package

Technical Evaluation

Architecture fit. Larastan is a development-only Composer dependency (composer require --dev) that extends PHPStan with Laravel-aware type resolution: it adds extensions, stubs, and Laravel-specific rules for facades, the service container, Eloquent models/relations, config, translations, and Blade views. Architecturally it is a static quality gate that lives in CI and the IDE, not a runtime component — it ships nothing to production, adds no request-path latency, and has zero production blast radius. That makes it a low-ceremony fit for a standard Laravel service or monolith.

The important nuance for a TPM: the README is explicit that this is not pure static analysis. Larastan boots the application container so it can resolve types that only exist at runtime. The tool therefore inherits your app's bootstrap preconditions (env vars, APP_KEY, DB/Redis reachability for some rules and model-schema inference from migrations). That single design choice drives most of the operational risk below.

Integration feasibility. Very high on a modern stack. Three steps: install as dev dependency, add a phpstan.neon/phpstan.neon.dist including vendor/larastan/larastan/extension.neon (plus the Carbon extension), point paths at app/, run ./vendor/bin/phpstan analyse. Effort is measured in hours to first run, days to a stable baseline, and 1–2 sprints to a level ratchet with team-wide conventions.

Hard gates to clear up front:

• PHP 8.2+ and Laravel 11.15/11.16+ for Larastan 3.x.
• Laravel 9–11 on Larastan 2.x; Laravel <9 on 1.x. These are effectively three different products with different PHPStan majors.
• Packages developed in-repo typically need orchestra/testbench to analyse correctly.
• Larastan 3 requires PHPStan 2; that coupling is not optional.

Technical risk (ranked).

1. Version lockstep. Larastan is pinned in practice to both a PHPStan major and a Laravel major. A Laravel upgrade and a Larastan/PHPStan upgrade become a three-body problem. Mitigation: treat the pair as one upgrade unit and budget for UPGRADE.md review.
2. Container boot side effects in CI. Analysis can fail or hang for reasons unrelated to code quality (missing env, absent PHP extensions). Release v3.9.5 fixing an infinite loop when the Redis extension is missing is a concrete illustration. Mitigation: a dedicated, documented CI job with a known-good env and pre-warmed DB if model schema inference is relied on.
3. False-positive volume. Laravel's "magic" still exceeds the analyser in places; the project maintains a public "errors to ignore" list precisely because of this. Unmanaged ignoreErrors regexes silently rot into a suppression layer that hides real defects.
4. Resource footprint. Allowed memory size exhausted is a first-class documented failure mode requiring --memory-limit=2G. Large codebases mean real CI minutes and wall-clock cost.
5. Signal vs. trust. A noisy first run on a legacy codebase can burn developer goodwill and get the gate disabled. Baseline discipline is the mitigation, and it is a process risk, not a tooling risk.

Note on the metadata: Dependents: 0 is a measurement artifact — dev dependencies are largely invisible to dependent-counting, and download badges in the README indicate very wide real adoption. 6,547 stars and a frequent 3.9.x patch cadence signal an actively maintained, de facto standard tool. The opportunity: 57.26 score reads as "valuable but not urgent": this is a hygiene and defect-prevention investment, not a differentiating capability.

Key questions for the team.

• What Laravel and PHP versions are in production today, and is any service still below Laravel 11.16 (forcing the 2.x line)?
• Do we already run PHPStan, Rector, or PHPCS? Rector carries its own PHPStan dependency and is the most likely Composer resolution conflict.
• What is the current escaped-defect rate and PR review latency — i.e., what is the counterfactual this tool improves?
• Who owns phpstan.neon, the baseline file, and the level ratchet? Without a named owner this decays in a quarter.
• Do we ship first-party Laravel packages (testbench burden) or Blade/translation-heavy UI (relevant to the newer rule sets)?
• What is our CI minute budget, and is a PHPStan result cache acceptable in the pipeline?
• What is our tolerance for a dev-tooling upgrade treadmill on a near-weekly patch cadence?

Integration Approach

Stack fit. Ideal: Laravel 11.16+/12/13 on PHP 8.2+ (3.9.3 explicitly added Laravel 13 support), Composer-based CI, and any existing PR gate (GitHub Actions, GitLab CI, Bitbucket Pipelines). Works alongside Pint, PHPCS, and Rector; the only real friction point is Composer constraint overlap between Larastan's required PHPStan major and whatever Rector/PHPStan plugins are already installed.

Migration path — three tracks depending on where we start:

Compatibility considerations.

• Pin exactly in composer.json/composer.lock and bump deliberately — the 3.9.x line shipped six patches in a short window, several of them behavioral.
• Never share a PHPStan config between the 2.x and 3.x lines; the config surface changed materially (some options removed, some rules enabled by default in 3.0).
• Keep the config in-repo and versioned (phpstan.neon.dist), with phpstan.neon local overrides gitignored — same convention as phpunit.xml.dist.
• Exclude generated/vendor-ish paths and squashed-migration edge cases explicitly rather than via broad regex ignores.

Sequencing.

1. Spike (1 week). Run against one representative service at level 5, capture error count, runtime, peak memory, and a sample of false positives. This produces the go/no-go and the sizing for CI.
2. Pilot (2 weeks). CI job on one service, non-blocking. Generate baseline. Triage the top false-positive classes into explicit ignoreErrors entries or code fixes.
3. Gate (1 sprint). Make the job blocking on new/changed code; publish the conventions doc (@phpstan-ignore-next-line for one-offs, config ignores only with a linked issue and expiry).
4. Standardise. Roll to remaining services/packages; add testbench config where first-party packages exist; enable the Laravel-specific rule sets (translations/Blade) where the app is view-heavy.
5. Ratchet. Move level 5 → 6 → 7 on a fixed cadence, shrinking the baseline only when it is regenerated deliberately. Treat the baseline as a debt register with a burn-down, not a permanent artifact.

Operational Impact

Maintenance. Two artifacts become code-owned infrastructure: phpstan.neon and phpstan-baseline.neon. Both need an owner and a review policy. The maintenance burden is dominated by upgrade events, not steady state: Larastan's coupling to PHPStan majors and Laravel majors means roughly one to two coordinated upgrades per year plus monthly patch bumps. Pin, schedule, and read UPGRADE.md on every major — 3.0 in particular removed config options and enabled rules by default, which silently changes results.

Support. MIT, community-maintained, three named maintainers, no commercial SLA or vendor escalation path. Responsiveness looks healthy (small, frequent, well-described PRs; new contributors landing regularly), but this is a dependency we must be able to live without. Mitigation: an internal champion who can read the errors-to-ignore and custom-config-parameters docs and, if needed, disable the gate without disabling delivery. Do not make the release pipeline depend on it being fixed upstream on our schedule.

Scaling. Analysis cost grows faster than linearly with codebase size and level. Practical levers: PHPStan's result cache in CI, parallel workers, scoped paths, and splitting monorepos into per-package runs (each with testbench where relevant). Budget for --memory-limit at 2G and above, and size CI runners accordingly. The trade-off is real but favourable: CI minutes and slower PR checks are exchanged for defect discovery before tests are written and before review.

Failure modes to plan for.

• Bootstrap failure — CI cannot boot the container (missing APP_KEY, env, DB, or a PHP extension). Manifests as hangs or opaque internal errors; the Redis-extension infinite loop fixed in 3.9.5 is the canonical example. Mitigation: dedicated CI job with an explicit, committed env fixture; timeout on the step.
• OOM kills — documented and common; harden with an explicit memory limit rather than relying on runner defaults.
• False-positive flood after an upgrade — a Laravel or PHPStan bump invalidates the baseline or changes inferred types; expect a burst of work and pre-book the capacity.
• Baseline drift / suppression rot — the highest long-term risk. A baseline regenerated casually, or an ignoreErrors list grown without review, converts the gate into theatre. Enforce: baseline only shrinks except at sanctioned regeneration points; every config ignore carries a ticket reference.
• Environment skew — a developer on PHP 8.2 vs. CI on 8.3 produces different results; standardise the PHP version across local and CI.

Ramp-up. Low for installation, moderate for value realisation. Developers need three habits, not deep training: how to read a PHPStan error, when to fix vs. @phpstan-ignore, and how to use Larastan's custom PHPDoc types to express intent on Eloquent models and relations (the 3.0 removal of automatic generic relation return types makes this an explicit team responsibility). Expect roughly 1–2 sprints from pilot to a self-sustaining gate, with one engineer carrying the tooling ownership at low ongoing cost.

Success measures to instrument from day one: error count above baseline (should trend to zero), baseline line count (should trend down), level (should trend up), PR check duration, and the count of code-quality defects found in CI rather than in review or production. If those last two don't move within two quarters, revisit the investment.