Blade Linter Laravel Package

Getting Started

luxplus/blade-linter is a dev-only quality tool that lints Blade templates — the gap Pint leaves behind, since Pint formats PHP but treats .blade.php files as opaque text.

composer require --dev luxplus/blade-linter
php vendor/bin/blade-linter --help   # confirm the binary name / flags on your install

If the package registers an Artisan command, php artisan list | grep -i blade will surface it; the CLI binary is the more stable entry point and the one to wire into scripts.

Where to look first:

1. Publish the config (php artisan vendor:publish --tag=blade-linter-config or the package's documented tag) and read the rule list. Rules are configured by name, and each rule owns its own options array.
2. Run it once against resources/views with no config changes. The default rule set is the fastest way to see which rules your codebase already violates.
3. Pick one rule and fix it across the repo before enabling the next. Blank-line and spacing rules touch nearly every file, so turning on five at once produces an unreviewable diff.

First use case: catching SiblingBlankLines violations — inconsistent blank lines around @if/@endif, @foreach, @section blocks. These are invisible in review and produce noisy diffs when different developers' editors disagree.

Implementation Patterns

Composer script as the contract. Add a script so every developer and CI runs the same invocation:

"scripts": {
    "lint:blade": "blade-linter resources/views",
    "lint": ["@lint:blade", "pint --test"]
}

CI as a gate, locally as a fixer. Run --test/dry-run mode in CI and fail the build; run the fixing mode locally before committing. If the linter only reports (no autofix), gate CI and let developers fix by hand — don't try to script rewrites.

Scope the file set deliberately. Point the linter at resources/views and your package view directories explicitly. Never point it at the project root: compiled views under storage/framework/views are generated PHP, and vendor/ is not yours to lint.

Tier the rules by churn. Enable structural rules (directive pairing, blank lines) first — they're mechanical. Defer stylistic rules that fight your team's existing formatting until you've done a formatting-only commit, so the diff isn't tangled with logic changes.

Per-rule opt-out over global disable. When a rule is wrong for a specific file (a generated view, a vendored component), prefer the package's ignore mechanism — inline ignore comments or a path exclusion list — over turning the rule off repo-wide. Document each suppression with a reason.

Pair with a pre-commit hook. A lint-staged-style setup that runs the linter only on staged .blade.php files keeps the feedback loop under a second and prevents the "CI is red, who broke it" round trip.

Gotchas and Tips

The 0.3.1 fix matters if you build with --no-dev. 0.3.1 makes SiblingBlankLines' element_directives option a plain boolean toggle and makes the package safe to load during composer install --no-dev. Before this, a production image build that still booted the package (service provider auto-discovery runs regardless of require-dev) could fail or misbehave because a dev-only code path was referenced. Pin ^0.3.1 in any project that builds production images with --no-dev — that's most of them. If you're on 0.3.0 and your deploys are fine, you're not affected yet, but the next unrelated --no-dev install may bite.

The element_directives option is a toggle, not a list. If you had 'element_directives' => ['@if', '@foreach'] in your published config, that's now the wrong shape — an array is truthy in PHP, so it will silently behave as true rather than filtering to those directives. Re-publish or hand-edit the config to a boolean. Silent truthiness coercions are the classic config-migration trap, and nothing will warn you.

Auto-discovery runs in production. Because the service provider registers even when the package is in require-dev but absent from the install, any config reference to classes or files that don't exist in the production tree is a deferred fatal. 0.3.1 closes this specific hole; keep the habit of running composer install --no-dev in a throwaway checkout before a release.

Blade is not PHP, and linting it is approximate. Multi-line @php ... @endphp blocks, directives embedded in HTML attributes (<div @class([...])>), and @verbatim sections are where every Blade tool trips. When a rule fires on something that looks correct, check whether the construct is inside @verbatim or an inline attribute before filing a bug.

Diff noise is the real cost. Blank-line rules will touch hundreds of files on first run. Land the formatting commit on its own, add the commit hash to .git-blame-ignore-revs, and only then enable the CI gate — otherwise every git blame in the repo points at the lint commit.

Debug a single rule against a single file. Almost every linter supports narrowing both the rule set and the path; use that rather than reading the full report. If a rule misfires, reduce the offending template to the smallest reproducing snippet before reporting upstream — the maintainer's fix in 0.3.1 came from exactly that kind of narrow report.

Extension point. Custom rules are the natural place to encode house conventions the package can't know about (e.g. "every @section must be preceded by a comment"). Check the rule interface before writing one; if the package exposes no extension hook, keep those checks in a separate script rather than forking.

Version churn is fast. This is a 0.x package — treat minor bumps as potentially breaking and read the changelog on every update. Pin to ^0.3 and let Renovate/Dependabot open PRs you actually read.