Laravel Blade Lint: Catch template errors before production

TL;DR

Install with composer require --dev magentron/laravel-blade-lint, then run php artisan blade:lint to validate all your Blade templates. Supports Laravel 5.4 through 11.

Installeer met composer require --dev magentron/laravel-blade-lint, voer dan php artisan blade:lint uit om al je Blade templates te valideren. Ondersteunt Laravel 5.4 tot en met 11.

Instala con composer require --dev magentron/laravel-blade-lint, luego ejecuta php artisan blade:lint para validar todas tus plantillas Blade. Compatible con Laravel 5.4 hasta 11.

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.

Het probleem: stille template fouten

Blade templates kunnen syntaxfouten bevatten die alleen aan het licht komen wanneer een gebruiker die specifieke pagina bezoekt. In tegenstelling tot PHP-bestanden die tijdens deployment op syntax worden gecontroleerd, worden Blade templates on-demand gecompileerd — wat betekent dat fouten onopgemerkt kunnen blijven tot in productie.

Veelvoorkomende problemen zijn:

Niet afgesloten @if, @foreach, of @section directives
Niet-matchende accolades in expressies
Ongeldige PHP syntax binnen Blade directives
Typefouten in directive namen

De oplossing: Laravel Blade Lint

Ik heb Laravel Blade Lint gemaakt om dit probleem op te lossen. Het is een eenvoudig Artisan commando dat al je Blade templates valideert door ze naar PHP te compileren en te controleren op syntaxfouten — zonder code uit te voeren.

Installatie

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

Voor Laravel 5.5+ wordt de service provider automatisch gevonden. Voor oudere versies voeg je de service provider handmatig toe aan config/app.php.

Basisgebruik

# Lint alle Blade templates
php artisan blade:lint

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

# Uitgebreide output
php artisan blade:lint -v

# Debug modus (toon gecompileerde PHP)
php artisan blade:lint --debug

Belangrijkste functies

Multi-process ondersteuning

Voor grote projecten met honderden templates detecteert de linter automatisch beschikbare CPU-kernen en verdeelt de validatie over meerdere worker processen. Dit kan het linten van grotere codebases aanzienlijk versnellen.

# Gebruik 4 parallelle processen
php artisan blade:lint -p 4

# Detecteer CPU-kernen automatisch (standaard)
php artisan blade:lint

CI/CD integratie

Het commando retourneert een non-zero exit code wanneer fouten worden gevonden, wat het perfect maakt voor CI pipelines:

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

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

Duidelijke foutrapportage

Wanneer fouten worden gevonden, krijg je duidelijke output met het bestand, regelnummer en foutmelding:

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

Ondersteunde Laravel versies

Het package is getest en onderhouden voor:

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

Vereisten

PHP 7.0+ (PHP 8.0+ voor Laravel 9+)
PCNTL extensie (voor multi-processing, optioneel)

Voeg het toe aan je workflow

Ik raad aan om Blade linting toe te voegen aan je pre-commit hooks of CI pipeline. Het duurt enkele seconden om uit te voeren en kan fouten vangen die anders alleen in productie zouden verschijnen.

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

Bekijk het project op GitHub. Issues en pull requests zijn welkom.

El problema: errores silenciosos en plantillas

Las plantillas Blade pueden contener errores de sintaxis que solo aparecen cuando un usuario visita esa página específica. A diferencia de los archivos PHP que se verifican sintácticamente durante el despliegue, las plantillas Blade se compilan bajo demanda, lo que significa que los errores pueden permanecer sin detectar hasta producción.

Los problemas comunes incluyen:

Directivas @if, @foreach, o @section sin cerrar
Llaves no coincidentes en expresiones
Sintaxis PHP inválida dentro de directivas Blade
Errores tipográficos en nombres de directivas

La solución: Laravel Blade Lint

Creé Laravel Blade Lint para resolver este problema. Es un simple comando Artisan que valida todas tus plantillas Blade compilándolas a PHP y verificando errores de sintaxis, sin ejecutar ningún código.

Instalación

# Instalar vía Composer
composer require --dev magentron/laravel-blade-lint

Para Laravel 5.5+, el proveedor de servicios se descubre automáticamente. Para versiones anteriores, agrega el proveedor de servicios manualmente a config/app.php.

Uso básico

# Validar todas las plantillas Blade
php artisan blade:lint

# Validar directorio específico
php artisan blade:lint resources/views/emails

# Salida detallada
php artisan blade:lint -v

# Modo debug (mostrar PHP compilado)
php artisan blade:lint --debug

Características principales

Soporte multiproceso

Para proyectos grandes con cientos de plantillas, el linter detecta automáticamente los núcleos de CPU disponibles y distribuye la validación entre múltiples procesos de trabajo. Esto puede acelerar drásticamente el linting en bases de código más grandes.

# Usar 4 procesos paralelos
php artisan blade:lint -p 4

# Detectar núcleos de CPU automáticamente (predeterminado)
php artisan blade:lint

Integración CI/CD

El comando devuelve un código de salida distinto de cero cuando se encuentran errores, haciéndolo perfecto para pipelines de CI:

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

# Ejemplo de GitLab CI
blade-lint:
  script:
    - php artisan blade:lint

Informe de errores claro

Cuando se encuentran errores, obtienes una salida clara que muestra el archivo, número de línea y mensaje de error:

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

Versiones de Laravel compatibles

El paquete está probado y mantenido para:

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

Requisitos

PHP 7.0+ (PHP 8.0+ para Laravel 9+)
Extensión PCNTL (para multiprocesamiento, opcional)

Añádelo a tu flujo de trabajo

Recomiendo agregar el linting de Blade a tus hooks de pre-commit o pipeline de CI. Toma segundos ejecutarse y puede detectar errores que de otro modo solo aparecerían en producción.

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

Consulta el proyecto en GitHub. Los issues y pull requests son bienvenidos.