Blade Compiler Plugin

The first-party Blade Compiler plugin surfaces errors from your application's configured Laravel Blade compiler during linting, before an affected template is rendered by an application request. It validates the compiler-generated PHP without executing it.

#Requirements

The plugin supports the following versions:

#Installation

Install the package as a development dependency. Laravel discovers its service provider automatically:

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

Add blade-compiler after your Core preset in config/sheath.php:

<?php

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

You can also select it for one run:

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

#What the Preset Enables

The preset enables one compiler-specific rule.

Sheath Core owns the Alpine, Livewire, and shared reactive rules. The Core recommended preset enables them independently of this plugin.

#Compiler Output Validation

blade-compiler-valid-output clones the application's BladeCompiler, compiles the template with its registered directives, precompilers, string preparation callbacks, and component configuration, then validates the resulting PHP. The isolated compiler copy prevents linting from changing Laravel's shared compiler state.

The rule catches malformed directives and echoes, component compilation failures, invalid output from application callbacks, and compile-time failures such as an illegal break, duplicate import alias, duplicate declaration, or invalid goto.

Generated template PHP is never executed. Native validation streams the output to the local PHP binary in lint-only mode, without writing a compiled view.

#PHP Validation Modes

Native process validation is the default because it detects PHP compile-time failures that the in-process parser cannot report:

<?php

return [
    'rules' => [
        'blade-compiler-valid-output' => ['error', [
            'phpValidation' => 'process',
        ]],
    ],
];

Set phpValidation to parser when the runtime cannot create subprocesses:

<?php

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

Parser validation uses token_get_all(..., TOKEN_PARSE) in the current PHP runtime. It does not evaluate the template, but it cannot detect every compile-time fatal that native php -l detects.

Process mode fails explicitly when proc_open or the PHP binary is unavailable. It does not treat an incomplete check as a clean template.

#Persistent Cache Identity

Persistent cache reuse is disabled for this rule by default. Reflection cannot discover every piece of runtime state that an application compiler callback may read.

If your compiler inputs are deterministic, set cacheIdentity to a deployment or build revision and change it whenever compiler callbacks, component classes, component discovery, or related configuration changes:

<?php

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

Sheath hashes the identity before adding it to the cache context.

#See Also

• Livewire and Alpine Markup
• Configuration
• CLI Usage
• Troubleshooting