fortephp / sheath-blade-compiler

v0.1.1 2026-08-25 02:34 UTC

Requires

• php: ^8.2
• ext-tokenizer: *
• fortephp/sheath: ^1.0
• laravel/framework: ^12.0 || ^13.0

Requires (Dev)

• laravel/pint: ^1.22
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.1
• rector/rector: ^2.1

MIT

• John Koster

• laravel
• blade linter

Published on Packagist.org on 2026-08-25 02:35 UTC

README

Catch PHP errors in compiled Blade templates before they reach production.

This Sheath plugin compiles your Blade views and checks the generated PHP for syntax and compile-time errors. It supports your application's custom directives and components without rendering views or executing their PHP.

Installation

composer require --dev fortephp/sheath-blade-compiler

Laravel discovers the package automatically. Add its preset to config/sheath.php:

'preset' => ['recommended', 'blade-compiler'],

Then run Sheath normally:

php artisan sheath:lint

You can also try the plugin without changing your config:

php artisan sheath:lint --preset=blade-compiler

What it catches

• malformed Blade directives and echoes;
• invalid PHP emitted by custom directives or compiler hooks;
• component compilation failures;
• PHP compile-time errors such as illegal break statements and duplicate imports;
• syntax errors inside @php blocks and native PHP tags.

Errors are reported in your Blade view rather than generated PHP, so they are easier to find and fix.

By default, the plugin starts a separate PHP process to check each compiled view. This catches compile-time errors that a simpler in-process parser can miss. If your environment does not allow PHP processes, use parser mode instead:

'rules' => [
    'blade-compiler-valid-output' => ['error', [
        'phpValidation' => 'parser',
    ]],
],

Caching

The rule reuses results across --cache runs by default. Template changes invalidate their own cached results automatically. If you change application-level Blade compiler behavior, such as custom directives, precompilers, or component registrations, delete .sheath-cache before the next run.

You can also supply a deployment or build revision with cacheIdentity. Changing it invalidates cached compiler results without exposing the original value in the compiler fingerprint:

'rules' => [
    'blade-compiler-valid-output' => ['error', [
        'cacheIdentity' => env('APP_BUILD_ID', ''),
    ]],
],

Set cacheAcrossRuns to false if the application changes compiler behavior at runtime and cached results must never be reused between command invocations:

'rules' => [
    'blade-compiler-valid-output' => ['error', [
        'cacheAcrossRuns' => false,
    ]],
],

Requirements

• PHP 8.2 or newer
• Laravel 12 or 13
• Sheath 1.x

License

MIT. See license.md.