Laravel Blade Lint Laravel Package

Technical Evaluation

Architecture fit. magentron/laravel-blade-lint is a single-purpose developer tool: an Artisan command that compiles Blade templates to catch syntax-level errors before they reach a rendered page. It sits in the same architectural slot as php -l, PHPUnit, or Pint — a dev-only, run-and-exit quality gate. It does not touch the request lifecycle, the container, service providers in production, or the data layer. That makes it a low-coupling addition: worst case it is removed with composer remove --dev and zero production impact. Fit is highest for teams with large resources/views trees, heavy use of @include/@component/@each, and no existing view-compilation step in CI.

Integration feasibility. Expected path is composer require --dev magentron/laravel-blade-lint, then invoking the command in CI. The main feasibility question is not "can we install it" but "does it resolve views correctly" — Blade linting requires bootstrapping enough of the Laravel application to locate view paths, namespaces (view()->addNamespace), and registered custom directives. Anything that requires a full app boot (database, cache, config from env) is an integration constraint we must validate early. Verify: supported Laravel/PHP version matrix, whether it lints by path glob or by view name, exit code semantics, and output format (plain text vs. machine-readable for CI annotations).

Technical risk.

• License — highest-severity item. GPL-3.0 is copyleft. Dev-only tooling that is used and not distributed is normally acceptable, but this needs a legal sign-off, not a TPM judgment call. It becomes material if we vendor, fork, patch, or ship it inside a distributed artifact (e.g., a packaged product, a Docker image we publish, a scaffolded starter kit). Compare against MIT/Apache alternatives before committing.
• Provenance. "Repository: unknown" plus 16 stars means we cannot confirm maintainer identity, CI status, test coverage, or security disclosure process. Treat as an unvetted third-party dependency and pin the version with a committed composer.lock.
• Abandonment / bus factor. A 16-star single-maintainer package has a realistic chance of going stale across a Laravel major. Blade's compiler is internal API and changes; a lint tool that reflects on compiled output is inherently coupled to it.
• Correctness ceiling. This is a syntax check. It will not catch missing variables, undefined components, wrong slot usage, authorization gaps, or @include of a nonexistent view if resolution is name-based. Do not let it be mistaken for view test coverage.

Key questions for the maintainer / spike.

1. Which Laravel and PHP versions are in the supported matrix, and is that matrix CI-enforced?
2. Does it lint custom directives registered by our app and by Livewire/Inertia/Filament?
3. What is the exit code on failure, and is there a JSON output for CI?
4. Does it require DB/cache/env access to boot, or can it run in a bare container?
5. Is the repo publicly auditable, and is there a security contact?
6. Has legal cleared GPL-3.0 for internal dev tooling in our distribution model?

Integration Approach

Stack fit. Assumes a standard Laravel app with Composer, Artisan, and a CI runner that already executes PHP tooling. No runtime dependency, no service, no infrastructure. It slots next to existing static-analysis steps and requires no change to application code, config, or deployment topology.

Migration path. Effectively greenfield — there is no incumbent to migrate from unless we are replacing an ad-hoc view:cache smoke step or a hand-rolled Blade::compileString script. Recommended sequence:

1. Spike (1 day). Install on a branch, run against the full view tree, record total error count and classify findings into genuine vs false positive from custom directives.
2. Baseline. If the existing codebase produces hundreds of pre-existing failures, do not gate on it. Either fix in bulk or scope the command to changed files first.
3. Advisory CI. Add to the pipeline as a non-blocking step for two sprints; track signal quality.
4. Blocking CI. Flip to required once false-positive rate is understood and an ignore mechanism is documented.
5. Local ergonomics. Add to a Composer script (composer lint:blade) and optionally a pre-commit hook so failures surface before the push, not after.

Compatibility. Two axes to confirm: Laravel major (Blade compiler internals shift between majors) and PHP minor. Pin the package version and re-run the spike as part of every Laravel upgrade checklist — that is the moment this class of tool breaks. Also confirm behavior under view:cache and with compiled views present, and that it tolerates @php blocks, nested components, and inline templates.

Sequencing relative to other work. Land it before a Blade-heavy refactor (component extraction, layout consolidation) so the refactor has a safety net; land it after any in-flight view rewrites to avoid attributing new failures to the tool. Independent of release trains — no customer-facing surface.

Operational Impact

Maintenance. Near-zero steady state: a version pin, a CI step, and an entry on the Laravel-upgrade checklist. The real cost is the exception list — every custom directive or legitimate-but-unlintable construct that produces a false positive needs a documented carve-out, or engineers will start ignoring the step. Assign one owner (typically the platform/tooling engineer) so pins and carve-outs do not rot.

Support. No vendor, no SLA. Support model is "we own the fork if it breaks." Budget a realistic half-day to patch or vendor a one-line fix if the maintainer goes dark mid-upgrade — which, at 16 stars, is a plausible scenario. Keep the dependency dev-only so an unpatched break never blocks a production deploy.

Scaling. Trivial. Runtime is proportional to view count and is a pure CPU/parse workload — sub-minute for most applications, low-minutes for very large trees. If it becomes slow, shard by directory or restrict to changed files in PR pipelines. No concurrency, memory, or state concerns.

Failure modes.

• False negatives — the dangerous one. Teams infer "views are tested" and reduce scrutiny. Mitigate by being explicit in the ADR that this is a syntax gate only.
• False positives on custom directives — erodes trust, leads to the check being disabled. Mitigate with a tracked ignore list and a rule that new directives get a lint exemption in the same PR.
• Silent no-op — the command lints zero files because of a path misconfiguration and exits 0. Worse than no check. Mitigate with a sanity assertion (linted-file count must exceed a floor).
• Break on Laravel upgrade — CI goes red for reasons unrelated to the change under review. Mitigate by pinning and treating upgrade validation as a scheduled task.
• Supply chain — unverified repo executing in CI with access to build secrets. Mitigate by running in a job with no deploy credentials, locking the version, and reviewing the diff on every bump.

Ramp-up. Minutes. One command, one CI line, one README note. No training program, no on-call implications, no runbook beyond "if it's red, fix the Blade syntax or add an exemption."

Recommendation. Adopt as an advisory-to-blocking dev-only check provided legal clears GPL-3.0 for our distribution model and the spike shows an acceptable false-positive rate on our custom directives. If either gate fails, the same outcome is achievable with a ~30-line in-house Artisan command wrapping Blade::compileString over resources/views — MIT-clean, fully owned, and adequate for the syntax-check job this package performs.