Laravel Blade Lint: detecta errores de plantillas antes de producción

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.

Si necesitas ayuda con desarrollo Laravel o calidad de código, no dudes en ponerte en contacto conmigo.