Larastan Laravel Package

Product Decisions This Supports

• Quality-gate investment in CI/CD. Larastan turns "code quality" from an aspiration into a pass/fail signal. A PM can attach it to the definition of done and to merge requirements, which converts an unbounded engineering concern into a measurable, enforceable policy.
• Technical debt prioritization and sequencing. PHPStan levels (1–10) plus the baseline file give you a ratchet: freeze existing debt, block new debt. That produces a defensible roadmap item ("reach level 5 this quarter, level 8 next") with a visible, monotonic metric instead of a vague "clean up the codebase" epic.
• Framework upgrade readiness. The release history explicitly tracks Laravel version support (3.x dropped Laravel <11 and added Laravel 13 support in v3.9.3). That makes it a cheap early-warning system for the deprecation/upgrade work you'd otherwise discover mid-migration. Relevant to any decision to stay current on Laravel versus pinning.
• Build vs. buy. This is effectively "adopt vs. buy" at zero license cost: MIT, dev-only dependency, maintained by the Laravel ecosystem's best-known maintainers, ~6.5k stars, steady release cadence with targeted fixes (e.g., Blade translation parsing, ENUM type inference, Redis-extension infinite loop). Building equivalent Laravel-aware type resolution in-house is not a credible option; the real decision is adoption timing and level target, not build vs. buy.
• Headcount and throughput planning. Static analysis catches whole classes of bugs before tests are written (per the maintainers' own framing), which shifts review time from nitpicking type errors to product logic. Useful input to arguments about review latency, onboarding ramp, and senior-engineer interrupt load.
• Use-case triage for where to apply it first. Best initial targets: long-lived revenue-critical services, teams of 3+ touching the same models/relations, codebases with heavy Eloquent relationship magic (where Larastan's Laravel-aware inference adds the most over vanilla PHPStan), and API layers where type drift causes client breakage.
• Scope boundary for the QA strategy. It informs the decision not to over-index on one tool: Larastan is a complement to tests and runtime observability, not a replacement. That framing keeps the quality budget balanced rather than single-threaded.

When to Consider This Package

Adopt when:

• The stack is Laravel 11.15+ on PHP 8.2+ (Larastan 3.x), or Laravel 9–11.16 (2.x) for older services. Below Laravel 9 you'd be on 1.x — evaluate whether that service is worth investing in at all.
• You have CI and a merge-review culture where a failing check actually blocks a merge. Without enforcement, the value collapses to a one-off audit.
• The codebase is large or long-lived enough that type errors reach production, or enough engineers touch shared code that implicit contracts drift.
• You're planning a Laravel major upgrade, a monolith decomposition, or a package extraction — all cases where catching implicit assumptions early is cheaper than catching them late.
• You want a low-risk pilot: it's a dev dependency, no runtime footprint, reversible in one commit, and the baseline lets you start at the current error count without a remediation project.

Look elsewhere or defer when:

• Non-Laravel PHP, or a Symfony/plain-PHP service — use PHPStan or Psalm directly rather than pulling in framework-specific extensions.
• Prototypes, spikes, or short-lived internal tools where the config and triage cost exceeds the bug-prevention benefit.
• Teams that will accept the tool, generate a baseline, and never ratchet the level — you'll pay the setup cost and book none of the benefit.
• Code that leans on unusual dynamic patterns Laravel-adjacent tooling can't model, where the ignore-list would grow to the point of making the gate meaningful only on paper. Read docs/errors-to-ignore.md first and judge how large that list would be for your code.
• You're analyzing a Laravel package rather than an application — requires orchestra/testbench and extra setup; still viable, but budget for it.
• Anyone expecting it to replace integration tests, contract tests, or observability. It cannot see runtime data, third-party responses, or infrastructure failure modes.

How to Pitch It (Stakeholders)

One-line summary: Larastan is a free, MIT-licensed, dev-only extension that teaches PHPStan how Laravel works, so the framework's "magic" becomes type-checkable and bugs get caught in CI instead of in production.

For executives: Zero license cost, no runtime impact, one-line install, removable in a single commit. It converts code quality from an unmeasurable engineering concern into a tracked metric — PHPStan level and error count — that we can put on a roadmap and report against. It also de-risks Laravel upgrades by surfacing deprecations and type mismatches before they become migration firefights. The expected return is fewer production defects and less senior-engineer time lost to review nitpicks, funded by roughly a day of setup and an ongoing trickle of triage.

For engineering: It boots the application container so it can resolve types that plain static analysis can't — Eloquent relations, facades, config, Blade translations, env, form requests. We start with a baseline so we don't block on legacy debt, then ratchet the level up over time. Typical sequence: install as a dev dependency, generate phpstan.neon at a modest level, commit the baseline, add phpstan analyse to CI as advisory for two weeks, then make it blocking for new and changed code. Realistic first milestones: level 5 on the highest-traffic modules, level 8 on new code, and an explicit, reviewed ignore-list that shrinks rather than grows.

Risks to name up front, honestly: initial noise on a mature codebase (mitigated by the baseline), occasional false positives where Laravel is genuinely too dynamic (mitigated by scoped ignores), and memory limits on very large codebases (--memory-limit). None of these are blocking, and all are contained to a dev dependency we can remove.