Cómo Configurar Laravel Pint con Git Hooks

Laravel Pint es una herramienta para formatear código PHP en proyectos Laravel, mientras que los Git hooks permiten automatizar tareas en momentos clave del flujo de trabajo de Git. Al combinarlos, puedes asegurarte de que el código esté correctamente formateado antes de cada commit, evitando problemas de estilo y mejorando la consistencia del proyecto.

Pasos clave:

• Instalar Laravel Pint: Si no está incluido en tu proyecto, añádelo con composer require laravel/pint --dev.
• Configurar un pre-commit hook: Crea un script en .git/hooks/pre-commit que ejecute Pint para los archivos PHP modificados.
• Compartir la configuración con el equipo: Usa una carpeta .hooks versionada y ajusta Git con git config core.hooksPath .hooks.

Este enfoque reduce errores, automatiza el formateo y asegura que todos los colaboradores sigan las mismas reglas de estilo. A continuación, se detalla cómo implementar esta integración paso a paso.

Instalación y Configuración de Laravel Pint

Verificar e Instalar Laravel Pint

En las versiones recientes de Laravel, Pint ya viene incluido y está listo para usarse. Para confirmar su presencia, revisa si el ejecutable está en ./vendor/bin/pint o busca "laravel/pint" en la sección require-dev del archivo composer.json.

Si trabajas con un proyecto más antiguo que no tenga Pint, puedes instalarlo fácilmente ejecutando:

composer require laravel/pint --dev

Una vez instalado, verifica que todo esté correcto ejecutando:

./vendor/bin/pint --version

Si el comando muestra la versión instalada, estás listo para usar Pint.

Ejecutar Laravel Pint desde la Línea de Comandos

Con Pint ya instalado, puedes formatear tu código directamente desde la línea de comandos. El comando básico es:

./vendor/bin/pint

Este comando formatea automáticamente todos los archivos PHP del proyecto.

Algunas opciones adicionales que pueden resultarte útiles son:

• --test: realiza una simulación de cambios sin modificar los archivos. Devuelve un código de salida distinto de cero si detecta problemas.
• --dirty: formatea únicamente los archivos con cambios no confirmados en Git.
• -v: muestra información detallada sobre las reglas aplicadas durante el proceso.

Configurar el Archivo de Configuración de Pint

Por defecto, Pint utiliza el preset laravel. Sin embargo, puedes personalizar su comportamiento creando un archivo pint.json en la raíz de tu proyecto. Este archivo te permite elegir entre diferentes presets estándar o definir tus propias reglas.

Un ejemplo básico de configuración en pint.json podría ser:

{
    "preset": "laravel",
    "exclude": [
        "storage",
        "bootstrap/cache"
    ]
}

En este caso, se especifica que las carpetas storage y bootstrap/cache deben ser ignoradas, lo cual es útil para omitir archivos PHP generados automáticamente.

Si necesitas modificar reglas específicas, puedes hacerlo añadiendo un objeto rules dentro del archivo de configuración. Por ejemplo:

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

Con esto, Pint estará configurado para ajustarse a las necesidades de tu proyecto. Ahora, puedes continuar con el siguiente paso y aprender cómo automatizar el formateo utilizando Git Hooks.

Crear un Git Pre-Commit Hook para Laravel Pint

Entender los Pre-Commit Hooks

Los hooks de Git son scripts que se ejecutan automáticamente en momentos clave del flujo de trabajo. En el caso de un pre-commit hook, este se activa justo antes de completar un commit. Su propósito principal es formatear el código y validar su sintaxis. Si algo falla en el proceso, el commit se cancela automáticamente.

Como lo describe Nihar Ranjan Das:

Git hooks are like having a bouncer at the door of your repository - they check everything before it gets in.

Esta herramienta resulta muy útil para evitar inconsistencias de formato en los Pull Requests y asegura que todos los desarrolladores sigan las mismas normas, sin importar cómo tengan configurado su entorno de desarrollo.

Escribir el Script Pre-Commit

El primer paso para crear este hook es generar un archivo llamado pre-commit (sin extensión) dentro de la carpeta .git/hooks/ de tu proyecto. Este script se encargará de identificar los archivos PHP en stage, formatearlos usando Pint y volver a añadirlos al commit.

Aquí tienes el contenido básico del script:

#!/bin/sh

FILES=$(git diff --cached --name-only --diff-filter=ACM -- '*.php')

if [ -n "$FILES" ]; then
    ./vendor/bin/pint $FILES -q
    git add $FILES
fi

• --diff-filter=ACM: Filtra únicamente los archivos añadidos, copiados o modificados.
• -q: Reduce la salida del comando para que el proceso sea más limpio.

Desde la versión 1.4 de Laravel Pint, también puedes usar el comando ./vendor/bin/pint --dirty para formatear exclusivamente los archivos modificados.

Configurar Git para Usar tu Hook Personalizado

Una vez que hayas creado el script, debes asegurarte de que sea ejecutable. Esto se logra con el siguiente comando:

chmod +x .git/hooks/pre-commit

Si no le otorgas permisos de ejecución, Git no podrá correr el script.

En caso de trabajar con Docker, como sucede con Laravel Sail, deberás adaptar el comando para ejecutarlo dentro del contenedor. Por ejemplo:

docker compose exec -T app vendor/bin/pint $FILES -q

El flag -T es crucial para evitar problemas relacionados con TTY al ejecutar comandos dentro de un contenedor.

Para facilitar el uso compartido de este hook en todo el equipo, puedes crear una carpeta versionada llamada .hooks/ en la raíz del proyecto. Luego, configura Git para que utilice esta carpeta como su directorio de hooks predeterminado:

git config core.hooksPath .hooks

De esta manera, todo el equipo trabajará con las mismas reglas, eliminando la necesidad de configuraciones manuales individuales.

Compartir Git Hooks en Todo el Equipo

Añadir Hooks al Control de Versiones

Por defecto, Git no sincroniza la carpeta .git/hooks debido a restricciones de seguridad, lo que significa que los hooks no se comparten automáticamente entre los miembros del equipo. Para solucionar esto, puedes crear un directorio versionado, como .hooks, en la raíz del proyecto y configurar Git para que lo utilice como ruta de hooks ejecutando el siguiente comando:

git config core.hooksPath .hooks

En mayo de 2023, el desarrollador Khant Zaw Hein implementó esta configuración sin necesidad de herramientas adicionales para Laravel Pint. Creó una carpeta .hooks e incluyó el comando anterior dentro del script post-autoload-dump en el archivo composer.json. Esto permitió que cualquier miembro del equipo que ejecutara composer install tuviera su entorno Git configurado automáticamente para ejecutar Pint en cada commit.

Con esta configuración, los hooks compartidos estarán listos para usarse, y el proceso será mucho más sencillo para nuevos colaboradores.

Crear un Script de Configuración para Nuevos Miembros

Para que los nuevos integrantes del equipo configuren Git automáticamente, puedes añadir un script al archivo composer.json. Este script ejecutará la configuración necesaria cada vez que se instalen las dependencias o se actualicen los autoloaders:

"scripts": {
    "post-autoload-dump": [
        "git config core.hooksPath .hooks"
    ]
}

De esta forma, cada vez que alguien ejecute composer install o composer dump-autoload, Git quedará configurado para usar los hooks compartidos.

Añadir Documentación al README

Aunque la configuración automatizada simplifica el proceso, es fundamental incluir instrucciones claras en el archivo README para que todo el equipo esté al tanto de cómo funciona. Como señala Grant McMullin, líder de equipo en Kirschbaum Development Group:

The basis of a great set of coding standards is not solely based on which rules you follow, but ensuring that everyone follows the same rules.

En el README, explica que Laravel Pint se ejecutará automáticamente en los archivos preparados para commit (stage) durante cada operación de commit. También menciona que, en casos excepcionales, se puede usar la opción --no-verify para omitir los hooks, aunque esto debería evitarse siempre que sea posible. Si el proyecto utiliza Docker, incluye instrucciones sobre cómo ejecutar Pint dentro del contenedor para garantizar que el entorno sea consistente para todos los desarrolladores.

Este enfoque asegura que todo el equipo esté alineado y que los estándares de codificación se apliquen de forma uniforme.

Probar y Solucionar Problemas Comunes

Probar Tu Pre-Commit Hook

Una vez que hayas integrado el pre-commit hook, es crucial asegurarte de que funcione correctamente y resolver cualquier problema que surja. Para probarlo, puedes modificar o crear un archivo PHP con errores de formato a propósito. Luego, añádelo con git add y ejecuta git commit. Si todo está configurado correctamente, Pint reformateará automáticamente los archivos preparados antes de completar el commit o bloqueará el proceso mostrando los errores de formato, dependiendo de cómo hayas configurado tu script.

También puedes usar opciones como --test para simular los cambios sin aplicarlos o --dirty para limitar el análisis solo a los archivos modificados. Esto te permitirá optimizar el proceso y ahorrar tiempo.

Solucionar Problemas Comunes

Si el hook no funciona como debería, aquí tienes algunos pasos para resolver problemas habituales:

• El hook no se ejecuta: Asegúrate de que el archivo del hook sea ejecutable con el comando chmod +x .git/hooks/pre-commit.
• Problemas en entornos Docker: Si estás utilizando Docker, añade la opción -T al comando para evitar problemas relacionados con TTY:

  docker compose exec -T app vendor/bin/pint
  

• Cambios no incluidos en el commit: Si Pint realiza correcciones pero estas no se incluyen en el commit, verifica que tu script ejecute git add sobre los archivos modificados después de aplicar las correcciones. Esto garantizará que las modificaciones se guarden sin interrumpir tu flujo de trabajo.

Revertir Cambios Después de que el Hook se Ejecute

Si Pint realiza cambios inesperados en tu código, puedes deshacer el commit manteniendo los cambios locales con el siguiente comando:

git reset --soft HEAD~1

Esto te permitirá revisar manualmente las modificaciones antes de confirmar nuevamente. Como señala Grant McMullin, líder de equipo en Kirschbaum Development Group:

There's no benefit in having beautifully formatted code that doesn't work. I mean obviously your 100% code-coverage test suite will catch this, but check it yourself, you know, just in case.

Si necesitas restaurar un archivo específico a su estado anterior, puedes usar git restore <archivo> o, si prefieres un método más tradicional, git checkout -- <archivo>. Además, para evitar sorpresas, siempre puedes ejecutar ./vendor/bin/pint --test y revisar qué cambios aplicaría Pint sin modificar realmente los archivos. Esto te dará un mayor control sobre el proceso de formateo.

Laravel Pint PHP Tests run automatically on before git commit using git hooks

Conclusión

Integrar Laravel Pint con Git hooks puede cambiar por completo la dinámica de tu flujo de trabajo al automatizar el formateo del código. Esto elimina discusiones innecesarias sobre estilos y permite que tu equipo se enfoque en lo que realmente importa: la lógica y la funcionalidad del proyecto.

El proceso es bastante directo: instalar Pint como dependencia de desarrollo, configurar un script de pre-commit que formatee automáticamente los archivos PHP, y compartir esta configuración con todo el equipo. Este enfoque asegura que no se introduzca código sin formatear, reduciendo revisiones innecesarias y mejorando la claridad del código.

Como se explicó anteriormente, combinar hooks locales con procesos de CI/CD añade una capa extra de protección, ayudando a mantener un estándar alto en la calidad del código. Paul Isaris, ingeniero de software, lo describe perfectamente:

Automating code formatting helps reduce human errors, eliminates minor formatting discussions in code reviews, and accelerates development workflows.

Además, esta automatización no solo garantiza consistencia, sino que también facilita la integración de nuevos desarrolladores al equipo. Un código uniforme y bien estructurado resulta más sencillo de entender y trabajar.

Adoptar esta solución no requiere mucho tiempo, pero los beneficios para la calidad y el mantenimiento de tus proyectos Laravel son duraderos. Tu equipo lo agradecerá, ya que podrán concentrarse en crear y mejorar sin preocuparse por detalles menores de estilo.

FAQs

¿Cómo puedo ajustar las reglas de Laravel Pint para mi proyecto?

Para ajustar las reglas de Laravel Pint según tus necesidades, puedes crear un archivo llamado pint.json en la raíz de tu proyecto. Este archivo te da la flexibilidad de establecer un preset (como laravel, psr12 o symfony) y personalizar reglas específicas. Por ejemplo, si prefieres usar la sintaxis corta para arrays, podrías configurar algo como esto:

{
  "rules": {
    "array_syntax": {"syntax": "short"}
  }
}

Con esta configuración, Laravel Pint aplicará las reglas que hayas definido automáticamente. Además, si deseas que el código se formatee automáticamente antes de cada commit, puedes configurar un hook pre-commit en Git para ejecutar Pint únicamente en los archivos modificados. Esto asegura que todo el equipo mantenga un código ordenado y uniforme.

¿Cómo soluciono problemas si el hook pre-commit de Laravel Pint no funciona?

Si el hook pre-commit no funciona como debería, hay varios pasos que puedes seguir para solucionarlo. Primero, verifica que el archivo exista, tenga permisos de ejecución y comience con la línea #!/bin/sh. Además, asegúrate de que la ruta a Laravel Pint sea correcta (vendor/bin/pint) y que esté instalado correctamente con el comando composer require laravel/pint --dev, si aún no lo has hecho.

Para depurar posibles errores, intenta ejecutar el script manualmente usando .git/hooks/pre-commit. También es importante comprobar que el formato de fin de línea sea LF (\n) y que la variable files esté configurada para detectar los archivos PHP modificados correctamente.

Si, después de estas verificaciones, el problema persiste, una solución puede ser eliminar el archivo pre-commit y crear uno nuevo siguiendo los pasos adecuados desde el principio.

Con estas comprobaciones, deberías poder solucionar cualquier inconveniente y asegurarte de que tu código se formatee automáticamente cada vez que realices un commit.

¿Cómo puedo compartir los Git hooks configurados para Laravel Pint con mi equipo?

Si quieres asegurarte de que todos los miembros del equipo utilicen los Git hooks configurados con Laravel Pint, puedes versionarlos y automatizar su configuración siguiendo estos pasos:

• Crea una carpeta para los hooks: En la raíz del proyecto, crea una carpeta llamada .githooks y guarda ahí el script pre-commit. Este script será el encargado de ejecutar Pint para formatear automáticamente los archivos PHP modificados antes de cada commit.
• Incluye la carpeta de hooks en el control de versiones: Añade la carpeta al control de versiones con git add .githooks/pre-commit y realiza un commit con un mensaje que explique el cambio. Esto permitirá que todos los miembros del equipo tengan acceso al hook.
• Configura Git para usar la carpeta personalizada: Ejecuta el comando git config core.hooksPath .githooks para indicarle a Git que utilice la carpeta .githooks en lugar de la predeterminada.
• Automatiza la configuración del equipo: Incluye el comando anterior en un script de configuración del proyecto, como composer install o un archivo setup.sh. De esta forma, cada vez que alguien clone o actualice el repositorio, los hooks se configurarán automáticamente.

Con este enfoque, todos los desarrolladores del equipo trabajarán bajo las mismas reglas de formato y el código estará siempre en orden antes de cada commit.

Publicaciones de blog relacionadas

• Cómo Usar Lazy Collections para Ahorrar Memoria en Laravel