Introduction

Getting Started

Sheath is a Laravel-first linter for HTML and Blade templates. It catches accessibility, security, correctness, and style problems during development and in CI. Existing projects can adopt it gradually with baselines and autofix.

#What Sheath Covers

Sheath combines built-in checks with configuration and rollout tools for new and existing projects:

  • accessibility, best practices, Blade, performance, security, and SEO rules
  • presets for common checks, strict analysis, style preferences, and migrations
  • safe fixes and dangerous fixes that require you to opt in, including a migration preset for older Blade syntax
  • inline suppressions and baselines for adopting rules gradually
  • output formats for terminals, continuous integration (CI), and other tools
  • custom rules for project-specific conventions

#Quick Start

Install Sheath, publish its configuration, and lint the configured paths:

composer require fortephp/sheath --dev

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

php artisan sheath:lint

Common workflows:

# lint the default configured paths

php artisan sheath:lint



# lint specific files or directories

php artisan sheath:lint resources/views

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



# apply safe fixes

php artisan sheath:lint --fix



# preview all safe and dangerous fixes

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



# generate a machine-readable report

php artisan sheath:lint --format=json

#Next Steps

Continue with the guide that matches your next task:

  • Installation: install Sheath and optional parallel support
  • Adoption Recipes: introduce Sheath to a new or existing project
  • Configuration: choose presets, paths, rule severities, and options
  • Rules: browse rules by package, category, severity, or autofix support
  • CI/CD Integration: add Sheath to a continuous integration workflow

#Behavior Notes

  • Sheath uses recommended when no preset is configured. Existing projects receive rules added to that preset in later releases. Use 'preset' => 'empty' to run only the rules you list.
  • Unknown rule IDs in config, --rule, or --only fail the run so CI cannot silently miss a rule. An unknown preset name will also fail.
  • Files with parser errors report those diagnostics first. Sheath skips rule checks for that file until you fix the syntax.
  • --print-config includes a ruleStatus section showing which rules will actually run.

#Example Output

resources/views/dashboard.blade.php

  ✗ 2:5  Images must have an alt attribute for accessibility. Use alt="" for decorative images.                           a11y-alt-text

  ⚠ 3:5  Buttons should have an explicit type attribute (button, submit, or reset) to prevent accidental form submission  best-practices-button-type

  ✗ 4:5  Links with target="_blank" must not enable window.opener. Remove rel="opener" or add rel="noopener".             security-no-target-blank



  2 errors, 1 warning



============================================================

Total: 2 errors, 1 warning in 1 file

2 problems can be automatically fixed