Laravel Blade Lint: Catch Template Errors Before Production

The problem: silent template errors

Blade templates can contain syntax errors that only surface when a user visits that specific page. Unlike PHP files that get syntax-checked during deployment, Blade templates are compiled on-demand — meaning errors can lurk undetected until production.

Common issues include:

• Unclosed @if, @foreach, or @section directives
• Mismatched braces in expressions
• Invalid PHP syntax within Blade directives
• Typos in directive names

The solution: Laravel Blade Lint

I created Laravel Blade Lint to solve this problem. It's a simple Artisan command that validates all your Blade templates by compiling them to PHP and checking for syntax errors — without executing any code.

Installation

# Install via Composer
composer require --dev magentron/laravel-blade-lint

For Laravel 5.5+, the service provider is auto-discovered. For older versions, add the service provider manually to config/app.php.

Basic usage

# Lint all Blade templates
php artisan blade:lint

# Lint specific directory
php artisan blade:lint resources/views/emails

# Verbose output
php artisan blade:lint -v

# Debug mode (show compiled PHP)
php artisan blade:lint --debug

Key features

Multi-process support

For large projects with hundreds of templates, the linter automatically detects available CPU cores and distributes validation across multiple worker processes. This can dramatically speed up linting on larger codebases.

# Use 4 parallel processes
php artisan blade:lint -p 4

# Auto-detect CPU cores (default)
php artisan blade:lint

CI/CD integration

The command returns a non-zero exit code when errors are found, making it perfect for CI pipelines:

# GitHub Actions example
- name: Lint Blade templates
  run: php artisan blade:lint

# GitLab CI example
blade-lint:
  script:
    - php artisan blade:lint

Clear error reporting

When errors are found, you get clear output showing the file, line number, and error message:

ERROR resources/views/users/profile.blade.php
  Line 42: syntax error, unexpected end of file, expecting "endif"

Supported Laravel versions

The package is tested and maintained for:

• Laravel 5.4, 5.5, 5.6, 5.7, 5.8
• Laravel 6.x, 7.x, 8.x, 9.x, 10.x, 11.x

Requirements

• PHP 7.0+ (PHP 8.0+ for Laravel 9+)
• PCNTL extension (for multi-processing, optional)

Add it to your workflow

I recommend adding Blade linting to your pre-commit hooks or CI pipeline. It takes seconds to run and can catch errors that would otherwise only appear in production.

# composer.json scripts
{
    "scripts": {
        "lint": [
            "php artisan blade:lint",
            "./vendor/bin/phpstan analyse"
        ]
    }
}

Check out the project on GitHub. Issues and pull requests welcome.