Phpstan Extension Laravel Package

Product Decisions This Supports

• Static analysis adoption in CI: This package is a PHPStan extension purpose-built for Laravel. It lets the team raise PHPStan levels on Laravel codebases without drowning in false positives caused by framework magic (facades, service container resolution, Eloquent magic properties, collection generics). That directly supports decisions like "gate PRs on static analysis" or "raise the PHPStan baseline threshold this quarter."
• Framework upgrade roadmaps: The 2.1.0 release adds test coverage against Laravel 12. That is the signal a PM needs when planning a Laravel 11 → 12 upgrade: the analysis tooling is tracking the framework, so quality gates won't block the upgrade. Treat this as a compatibility checkpoint on the upgrade timeline, not a feature delivery.
• Build vs. buy: Teams routinely consider writing bespoke PHPStan rules to teach the analyser about their own Laravel conventions. This package is the "buy/adopt" baseline that removes the need to reinvent framework-level rules; custom rules should be reserved for domain-specific invariants (e.g. "all money values must use the Money cast").
• Tech-debt and refactor investment: Higher static-analysis coverage gives measurable evidence for refactor business cases — error counts, suppressed-ignore counts and baseline size become the metrics you cite when asking for engineering time.
• Use cases: pre-merge quality gates, legacy Laravel modernisation programmes, onboarding new engineers to a large Laravel codebase (the analyser documents implicit framework behaviour), and post-incident prevention work.

When to Consider This Package

Adopt when:

• The codebase is Laravel (or Laravel-adjacent packages) and PHPStan is already, or is about to be, part of CI.
• The team is stuck at low PHPStan levels because framework magic produces noise, or is maintaining a large ignoreErrors list / baseline that nobody trusts.
• A Laravel major-version upgrade is on the roadmap — the 2.1.0 release confirms Laravel 12 is exercised in CI, so it is a reasonable pairing with that upgrade.
• You want static analysis as a team-wide standard rather than per-developer preference.

Look elsewhere or deprioritise when:

• The stack is not Laravel, or the Laravel surface area is trivial (a few simple controllers) — the framework-specific rules add little.
• The team has not adopted PHPStan at all and has no intention of doing so; this package is an amplifier for an existing practice, not a substitute for one.
• You are on very old PHPStan or Laravel versions — verify the version constraints in the package's composer.json before committing, since this release only evidences Laravel 12 testing, not a broad compatibility matrix.
• You need a linter with zero configuration and no PHP expertise to operate; PHPStan plus extensions has a real setup and maintenance cost.

Note on this release specifically: 2.1.0 is a maintenance release — a Dependabot bump for fetch-metadata and added Laravel 12 test coverage. No new features, no deprecations, no breaking changes. Upgrade risk is low and no migration work is implied; treat it as routine maintenance and fold it into the next dependency-refresh cycle.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost dependency that makes our automated code review smarter about Laravel specifically. It converts framework "magic" — the parts of Laravel that normally confuse static analysis — into checks that actually work, which means defects get caught before merge instead of in QA or production. The latest release confirms it works with Laravel 12, so adopting it now also de-risks our planned framework upgrade. Cost is a one-off CI configuration effort plus negligible ongoing maintenance; the return is fewer escaped defects and a defensible quality bar.

For engineering: soyhuce/phpstan-extension extends PHPStan with Laravel-aware behaviour, so we can push to higher levels without an unreadable ignore-list. 2.1.0 is a maintenance release: Dependabot bump on the metadata action, and tests now run against Laravel 12 — no API changes, no breaking changes, safe to bump. Recommendation: adopt it as the baseline extension alongside PHPStan, keep custom rules for our own domain invariants, and track baseline size and ignored-error count as our quality metrics over time.