Phpstan Blade Rule Laravel Package

Product Decisions This Supports

• Build vs. buy for template-layer quality gates. Blade templates are PHP-adjacent but invisible to standard PHPStan analysis. This package closes the gap for a fraction of the cost of building and maintaining an in-house Blade rule set — relevant whenever the roadmap includes hardening CI for a mature Laravel app.
• Roadmap sequencing for static analysis adoption. If your engineering org is phasing in PHPStan (level-by-level), this rule belongs in the "templates" phase, after controllers/models baselining. The v0.4 @include scoping fix materially affects that sequencing: teams that tried this rule earlier and hit false positives on partials now have a reason to re-evaluate.
• Prioritizing refactors of Blade partials. Better variable-scoping fidelity on @include means views that use include-heavy composition (layouts, component partials, shared fragments) become analyzable. Supports a decision to consolidate or refactor partials rather than rewrite them as Livewire/Inertia components on the assumption that Blade is un-analyzable.
• Deciding whether template errors get caught pre-merge vs. in production. Undefined-variable and type errors in views are typically discovered by users. Adoption shifts detection left, which is a reliability/incident-reduction input rather than a feature input.
• Evaluating migration to Inertia/Livewire. A team may justify a front-end architecture migration partly on "Blade gives us no type safety." This package weakens that argument for the Blade portions, so the migration business case should be judged on interactivity/DX, not on analyzability.

When to Consider This Package

Consider it when:

• The project is Laravel, on a PHPStan setup already in CI, and views carry meaningful logic (conditionals, loops, @include/@each composition, non-trivial variable passing).
• You have recurring production bugs traceable to view variables — missing keys, wrong types, @include not receiving expected data.
• You want template coverage without a full front-end rewrite; the team is willing to run PHPStan as a dev dependency at a pinned version.
• You can tolerate the maturity level implied by a 0.x version line: expect occasional false positives and pin versions in composer.json.

Look elsewhere or wait when:

• The codebase is Blade-light (thin views, logic in Livewire/Inertia/Vue), where the rule's surface area is small relative to setup cost.
• The team has no PHPStan baseline and no appetite for CI gating — a template rule alone won't be adopted; the org needs the broader static-analysis habit first.
• You need vendor-backed SLAs or long-term support guarantees; this is a single-maintainer community package, and a 0.x line can introduce behavioral changes in minor releases.
• Baseline-generation churn is unacceptable: false positives on complex @include/@component patterns may require per-file ignores, which some teams treat as a code smell. Do a trial run on the messiest views before committing.

The v0.4 fix is a maintenance-grade improvement, not a new capability — it removes a known source of @include false positives. It changes the evaluation calculus only for teams that previously trialed and abandoned the rule for that reason.

How to Pitch It (Stakeholders)

For executives: A small, low-cost quality gate for the view layer of our Laravel app — the one part of the codebase standard static analysis can't see. It catches template bugs (missing or mistyped variables) before customers do. Cost is a dev-only dependency and a CI step; there's no runtime footprint and no vendor lock-in. Treat it as a reliability improvement, not a platform bet, and expect to pin the version given its early (0.x) maturity.

For engineering: canvural/phpstan-blade-rule extends PHPStan to Blade templates, catching undefined variables and type mismatches in views. v0.4 fixes @include variable scoping — the main known false-positive source — so include-heavy partials are now worth analyzing. Add as a require-dev, pin the version, generate a baseline, and gate new code rather than retrofitting the whole view tree at once. Expect some iteration on ignores for exotic directive usage; budget a short spike on our most complex views to size that.