Phpstan Blade Rule Laravel Package

Technical Evaluation

Architecture fit. canvural/phpstan-blade-rule is a PHPStan extension that brings Blade templates into the existing static-analysis pipeline. It is a dev-only dependency with zero production footprint: no service provider shipped to runtime beyond dev, no database, no queue, no config surface in config/. Architecturally it fits anywhere the team already treats PHPStan as the quality gate — it extends an existing concern rather than introducing a new one. For a Laravel monolith or a modular codebase with many packages, it closes a well-known blind spot: application code is analysed, templates are not.

Integration feasibility. Low effort. composer require --dev canvural/phpstan-blade-rule, one includes: entry in phpstan.neon, and a path glob for views. No application code changes, no migration, no runtime behaviour change. It can be trialled in a single CI job before anyone is blocked by it.

Technical risk.

• Pre-1.0 surface. At v0.4 the package makes no stability promise; a 0.x minor bump may contain breaking changes. Pin the version and upgrade deliberately.
• Coupling to PHPStan internals. The rule hooks into PHPStan's rule registry and node/type resolution, so PHPStan major upgrades are the most likely source of breakage. Budget a compatibility check on every PHPStan bump.
• False positives are the dominant risk, not missed bugs. Blade is dynamically typed by nature — @include argument scoping, @each, components, view composers, View::share, and @php blocks all produce variables the analyser cannot always see. A noisy rule erodes trust in the whole PHPStan gate.
• Signal quality change in v0.4. The @include variable-scoping fix removes a specific class of incorrect diagnostics around variables passed into or inherited by an included view. This is a false-positive reduction, not new capability — it should shrink the ignoreErrors baseline rather than change behaviour for clean templates.
• Single maintainer. One author, low release cadence (v0.3 → v0.4). Acceptable for a dev-only tool; not acceptable if it ever becomes a hard merge blocker without an internal fallback.

Key questions.

1. Which PHPStan major/minor range and which PHP and illuminate/view versions does v0.4 declare support for? 2 Does the extension resolve variables contributed by view composers, View::share, and Blade components, or only lexically visible assignments?
2. What is the wall-clock overhead on our largest view directory, and does it cache between runs in CI?
3. Can findings be reported non-blocking first (separate CI job, warning-only) so we can measure noise before enforcing?
4. What is our exit plan if the maintainer stops releasing — pin and vendor, or drop the rule?

Integration Approach

Stack fit. Requires an existing PHPStan setup in CI. If PHPStan is not yet standardised across the codebase, the Blade rule is a second step, not the first — introducing both at once conflates two sources of new findings and makes triage impossible.

Migration path. Purely additive and opt-in. There is no state, no schema, and nothing to roll back beyond removing two config lines. The pragmatic path: run it in report-only mode on the full view tree, capture the finding count, and decide whether the volume is worth the enforcement cost.

Compatibility. Two dimensions must be checked before adopting v0.4: the PHPStan version constraint (this is the tightest) and the Laravel/Illuminate version constraint for Blade compilation. Since this is a 0.x release, treat the composer.json constraints as the source of truth rather than assuming the latest of everything works.

Sequencing.

1. Confirm PHPStan version alignment; upgrade PHPStan first if needed, since Blade-rule upgrades will always trail it.
2. Add the dev dependency and config to a branch; run report-only in CI.
3. Triage the initial finding set: real undefined-variable bugs vs. dynamic-Blade false positives. Fix the former, baseline the latter — and keep the baseline file small and commented.
4. Re-run on v0.4 specifically; the @include scoping fix should retire baseline entries that were never real defects. Verify rather than assume — remove the entries and confirm they stay green.
5. Only then promote the job to blocking. Pin the exact version in composer.json and review the next 0.x bump like a minor-breaking change.

Operational Impact

Maintenance. Low steady-state cost: one dev dependency, one config entry, one CI job. The real maintenance burden is the ignoreErrors baseline — every new dynamic pattern invites an entry, and an unmanaged baseline quietly becomes a suppression list. Assign ownership and require a comment per entry.

Support. Community-supported by a single maintainer. No SLA, no vendor. Internal support burden falls on whoever owns the PHPStan setup, and that person should be able to read the rule's source if needed — it is a small package.

Scaling. Analysis time grows with the number of templates compiled. On large view trees this can add meaningful seconds to CI; run it in the same job as the PHP job rather than a new one to reuse warm caches, and measure before rolling out repo-wide. Scope to resources/views and package view directories explicitly rather than globbing broadly.

Failure modes.

• False-positive spike after a framework or PHPStan upgrade — most likely failure; manifests as a red build on unchanged templates. Mitigate with pinned versions and a habit of testing upgrades on a branch.
• Rule silently stops analysing — if the view path glob is wrong or the extension include is dropped, the job goes green for the wrong reason. Guard with a deliberately failing fixture template or a sanity assertion that the rule reports a known-bad view.
• PHPStan incompatibility — the extension crashes or is skipped, again producing a false green. Same guard applies.
• Maintainer abandonment — pin and accept static behaviour; the tool degrades gracefully since it is dev-only.

Ramp-up. Near zero for developers: findings arrive as ordinary PHPStan errors in a familiar output format. The ramp-up cost is on the platform/CI owner (half a day to wire up, triage, and baseline) and on reviewers, who need a shared convention for when a Blade finding is a real bug versus an analyser limitation. v0.4 is a small, non-breaking quality fix and does not change the adoption calculus — it modestly improves the ratio of true findings to noise, which is exactly the currency this kind of tool trades in.