Introduction

Adoption Recipes

Use these recipes when you know what kind of project you have and want a ready-to-copy starting point.

#New Laravel App

Start strict. New applications usually have little historical template debt, so it is cheaper to prevent issues than to baseline them.

composer require fortephp/sheath --dev

php artisan vendor:publish --tag=sheath-config

php artisan sheath:lint --fix

php artisan sheath:lint --max-warnings=0

Raise the preset in config/sheath.php, and add stylistic if you want to enforce a house style during the initial rollout:

'preset' => ['strict', 'stylistic'],

A portable CI command:

php artisan sheath:lint --max-warnings=0 --cache

Keep the preset's rules enabled unless one conflicts with a project convention. If that happens, change the rule severity in config/sheath.php rather than ignoring broad directories.

#Existing App

Start with the default recommended preset, which is tuned to stay quiet on correct Blade. Generate a baseline first, then shrink it over time.

composer require fortephp/sheath --dev

php artisan vendor:publish --tag=sheath-config

php artisan sheath:lint --generate-baseline

git add config/sheath.php sheath-baseline.json

git commit -m "Add Sheath baseline"

After that, normal lint runs filter known historical findings while still reporting new ones:

php artisan sheath:lint

When you fix a batch of issues:

php artisan sheath:lint --fix

php artisan sheath:lint --update-baseline

#Security And Accessibility First

If you want a focused rollout, start with rules that catch high-signal security and accessibility problems.

php artisan sheath:lint --only=security-csrf-field,security-no-target-blank,security-no-raw-echo,a11y-alt-text,a11y-form-label,a11y-button-accessible-name

In config:

'rules' => [

    'security-csrf-field' => 'error',

    'security-no-target-blank' => 'error',

    'security-no-raw-echo' => 'warning',

    'a11y-alt-text' => 'error',

    'a11y-form-label' => 'error',

    'a11y-button-accessible-name' => 'error',

],

This configuration gives teams immediate correctness feedback while leaving style and SEO decisions for a later rollout.

#Component Library

For Blade component-heavy projects, run a targeted pass over component templates first.

php artisan sheath:lint --components --only=blade-require-props,blade-component-self-closing,blade-no-directive-space,blade-no-debug

If component internals intentionally violate document-level rules, keep the component path focused in local commands and CI jobs instead of disabling useful rules globally.

#Local Development

Use fast, narrow commands while you are editing:

php artisan sheath:lint resources/views/components/button.blade.php

php artisan sheath:lint --only=a11y-alt-text,security-csrf-field

php artisan sheath:lint --fix

Use --dry-run before broader fix passes:

php artisan sheath:lint --dry-run

php artisan sheath:lint --dry-run --dangerous

You must opt in before Sheath applies dangerous fixes because they can remove behavior, attributes, or markup. Review them before applying.

#Windows Development

Parallel mode works on Windows after you install the optional runtime packages. Combine it with caching when both improve your workload:

php artisan sheath:lint --parallel --cache

Use --parallel-if-available when a shared command should run sequentially without a warning on machines that do not have those packages.

#Package-Aware Rules

If a rule seems missing, inspect the resolved config first:

php artisan sheath:lint --print-config

Look at the ruleStatus section. Some rules are skipped because a required Composer package is not installed or is the wrong version. See packageRequirementMode.

#Suppressing Legitimate Findings

Use the narrowest suppression that fits, so the rule keeps its coverage everywhere else. See Choosing a Suppression for the options, from a single line up to a baseline.

#CI Rollout

For GitHub Actions, the same command works for both new projects and existing apps with a committed baseline:

- name: Lint Blade templates

  run: php artisan sheath:lint --format=github --max-warnings=0 --cache

Sheath automatically applies sheath-baseline.json from the project root unless you pass --ignore-baseline.

#See Also