Laravel Pint

Herramienta de corrección automática de estilo de código construida sobre PHP CS Fixer. Explicamos cómo mantener un estilo de código consistente en equipo.

​

¿Qué es Laravel Pint?

Laravel Pint es una herramienta de corrección automática de estilo de código construida sobre PHP CS Fixer. Está diseñada para funcionar sin configuración desde el primer momento y formatear automáticamente el código siguiendo el estilo de Laravel.

Al automatizar los típicos “comentarios de revisión sobre estilo de código” en el desarrollo en equipo, puedes centrarte en las revisiones que realmente importan.

​

Instalación

Las aplicaciones Laravel recién creadas incluyen Pint automáticamente. En proyectos con versiones antiguas, instálalo con Composer.

composer require laravel/pint --dev

​

Formas de ejecutarlo

​

Uso básico

Corrige automáticamente todos los archivos .php del proyecto.

./vendor/bin/pint

También puedes limitar el alcance a un archivo o directorio.

./vendor/bin/pint app/Models
./vendor/bin/pint app/Models/User.php

​

Lista de opciones

Opción	Descripción
--test	No modifica los archivos, solo detecta errores de estilo. Devuelve un código de salida distinto de cero si los hay
--dirty	Aplica solo a los archivos con cambios no confirmados en Git
--diff=[branch]	Aplica solo a los archivos con diferencias respecto a la rama indicada
--repair	Corrige errores de estilo y, si hubo correcciones, devuelve un código de salida distinto de cero
--parallel	Modo de ejecución en paralelo (experimental) para mejorar el rendimiento
--max-processes=4	Se combina con --parallel para indicar el número máximo de procesos
-v	Muestra detalles de los cambios
--config	Indica la ruta del pint.json a usar
--preset	Indica el preset a usar

# Solo comprobar, sin modificar archivos
./vendor/bin/pint --test

# Solo archivos sin confirmar
./vendor/bin/pint --dirty

# Ejecución en paralelo
./vendor/bin/pint --parallel

​

Configuración

Puedes personalizar el comportamiento creando un pint.json en la raíz del proyecto.

{
    "preset": "laravel"
}

También puedes indicar explícitamente la ruta del archivo de configuración.

./vendor/bin/pint --config vendor/my-company/coding-style/pint.json

​

Presets

Un preset es un conjunto de reglas. El preset por defecto es laravel, con las reglas más adecuadas para proyectos Laravel.

Preset	Descripción
laravel	Estilo de código recomendado por Laravel (por defecto)
psr12	Estándar PSR-12
per	PER Coding Style
symfony	Estilo de Symfony
empty	Sin reglas. Se usa definiendo reglas por separado

# Indicar el preset desde la línea de comandos
./vendor/bin/pint --preset psr12

​

Personalizar reglas

En pint.json puedes activar o desactivar reglas individualmente. Las reglas disponibles se encuentran en PHP CS Fixer Configurator.

{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true,
        "array_indentation": false,
        "new_with_parentheses": {
            "anonymous_class": true,
            "named_class": true
        }
    }
}

​

Exclusión de archivos y carpetas

Puedes excluir carpetas concretas del análisis.

{
    "exclude": [
        "my-specific/folder"
    ]
}

Para excluir por patrón de nombre de archivo, usa notName.

{
    "notName": [
        "*-my-file.php"
    ]
}

Para excluir por ruta específica, usa notPath.

{
    "notPath": [
        "path/to/excluded-file.php"
    ]
}

​

Configuración recomendada

Un ejemplo de pint.json que funciona bien en el día a día:

{
    "preset": "laravel",
    "rules": {
        "no_unused_imports": false,
        "strict_comparison": true,
        "declare_strict_types": true
    }
}

Motivo para añadir cada regla:

Regla	Efecto
no_unused_imports	Al ponerla en false, no se eliminan los use no utilizados. En Pint su valor por defecto es true (eliminar), por lo que en un proyecto Laravel habitual no hace falta esta línea
strict_comparison	Convierte == en === y != en !==, evitando bugs por conversiones de tipo inesperadas
declare_strict_types	Añade automáticamente declare(strict_types=1); al principio del archivo, mejorando la seguridad de tipos

strict_comparison y declare_strict_types fuerzan un código estricto en tipos, así que al añadirlas a un proyecto existente puede haber muchas correcciones la primera vez. En proyectos nuevos conviene introducirlas desde el principio.

no_unused_imports es una configuración pensada para desarrollo de paquetes. El valor por defecto de Pint es true (elimina los use no utilizados), así que en un proyecto Laravel normal esta línea no es necesaria. En el desarrollo de paquetes existe el patrón de activar/desactivar funcionalidades mediante imports de traits o interfaces, así que resulta práctico dejarla en false y cambiarla a true según cada paquete.

​

Configuración de scripts en composer.json

Al registrar scripts para Pint en composer.json, puedes ejecutarlo solo con composer pint.

{
    "scripts": {
        "pint": "./vendor/bin/pint",
        "pint:test": "./vendor/bin/pint --test"
    }
}

Después de registrarlos, puedes usarlos así:

# Corregir el código automáticamente
composer pint

# Solo comprobar (sin corregir)
composer pint:test

En CI, composer pint:test te permite detectar violaciones sin modificar archivos. Como --test devuelve un código de salida distinto de cero cuando hay errores, sirve como comprobación de paso/fallo en CI.

​

Ejecución automática con GitHub Actions

Con GitHub Actions puedes ejecutar Pint y confirmar automáticamente las correcciones en cada push.

1. Configurar los permisos del workflow

   En el repositorio de GitHub, entra en Settings > Actions > General > Workflow permissions y activa “Read and write permissions”.

2. Crear el archivo del workflow

   Crea .github/workflows/lint.yml.

   name: Fix Code Style
   
   on: [push]
   
   jobs:
     lint:
       runs-on: ubuntu-latest
       strategy:
         fail-fast: true
         matrix:
           php: [8.4]
   
       steps:
         - name: Checkout code
           uses: actions/checkout@v5
   
         - name: Setup PHP
           uses: shivammathur/setup-php@v2
           with:
             php-version: ${{ matrix.php }}
             tools: pint
   
         - name: Run Pint
           run: pint
   
         - name: Commit linted files
           uses: stefanzweifel/git-auto-commit-action@v6
   

Este workflow ejecuta Pint en cada push y confirma automáticamente los archivos corregidos.

Como la corrección se aplica antes de la revisión del pull request, se reducen los comentarios sobre estilo de código. Cuando lo introduzcas en el equipo, corrige primero localmente todos los archivos y añade después el workflow para evitar commits sobrantes.