Guía completa para usar Larastan en Laravel

En el mundo del desarrollo de software, escribir código sin errores es fundamental para el éxito de cualquier proyecto. En Laravel, una de las mejores herramientas para detectar posibles fallos en tu código es Larastan, una extensión de PHPStan diseñada específicamente para este framework. A lo largo de este artículo, te guiaré en cómo instalar y configurar Larastan, cómo ejecutarlo con Sail, y cómo aprovechar los 9 niveles de análisis que ofrece. Así, podrás llevar la calidad de tu código al siguiente nivel, reduciendo errores y mejorando la robustez de tus aplicaciones.

¿Qué es Larastan?

Larastan es una herramienta de análisis estático creada sobre PHPStan, pensada para analizar código Laravel y detectar errores potenciales antes de que el código sea ejecutado. El análisis estático te permite identificar problemas en tu código de manera temprana, ayudándote a corregir errores antes de que lleguen a producción.

¿Qué tipo de problemas detecta?
Desde errores simples como invocar métodos inexistentes en modelos o controladores, hasta fallos más complejos relacionados con el tipado de variables y retorno de funciones.

Principales características de Larastan:

• Detección de errores sin necesidad de ejecutar el código.

• Soporte para muchas características específicas de Laravel, como Eloquent, controladores, migraciones, y más.

• Mejora de la calidad del código y la detección de errores a medida que avanzas por sus niveles de análisis.

Instalación de Larastan

Paso 1: Instalar Larastan

Lo primero es instalar Larastan utilizando Composer. Ejecuta el siguiente comando para añadirlo como una dependencia de desarrollo.

Paso 2: Configuración básica

Después de instalar Larastan, necesitas crear un archivo de configuración para PHPStan. Este archivo generalmente se llama phpstan.neon y se coloca en la raíz de tu proyecto. Aquí un ejemplo de configuración básica:

Paso 3: Ejecutar Larastan

Si estás utilizando Laravel Sail, puedes ejecutar Larastan directamente con el siguiente comando:

Para aquellos que no usan Sail, el comando estándar es:

Este comando iniciará el análisis estático de los archivos en las rutas especificadas (en este caso, app). Asegúrate de ajustar los paths según tus necesidades.

Niveles de análisis de Larastan

Larastan tiene 9 niveles de análisis, cada uno más estricto que el anterior. A medida que aumentas el nivel, se vuelven más exigentes en cuanto a la detección de posibles errores. Vamos a detallar cada nivel:

• Nivel 1: El análisis más básico. Detecta errores graves, como invocar métodos que no existen en un objeto. Es el punto de partida perfecto para proyectos en etapa inicial.

• Nivel 2: Introduce más validaciones sobre el uso de tipos y retornos de funciones. Aquí, Larastan empezará a exigir que el código tenga tipado básico.

• Nivel 3: Larastan empieza a ser más riguroso con el tipado de variables, asegurándose de que las funciones y métodos devuelvan los tipos de datos esperados.

• Nivel 4: Se amplían las comprobaciones, especialmente en estructuras condicionales, verificando que siempre se utilicen de manera lógica y no redundante.

• Nivel 5: Aquí Larastan empezará a detectar inconsistencias en tu código, como variables no definidas o mal asignadas.

• Nivel 6: Se intensifica la verificación de los retornos y argumentos de los métodos, asegurándose de que el tipado sea siempre respetado. A este nivel, las funciones mal tipadas se reportarán de manera estricta.

• Nivel 7: Larastan empezará a alertar sobre posibles tipos mixtos, lo que obliga a los desarrolladores a ser más cuidadosos con las definiciones de tipo en su código.

• Nivel 8: Larastan revisará profundamente las clases y los métodos, buscando sobreescrituras incorrectas o problemas relacionados con la herencia.

• Nivel 9: Este es el nivel más estricto. A este punto, Larastan analiza exhaustivamente el código para encontrar cualquier detalle mal estructurado o ambiguo. Aquí ya deberías tener tu código en una condición impecable.

Consejo: Comienza con un nivel más bajo (como el 3 o 5) si tienes un proyecto grande y sube el nivel gradualmente para asegurarte de que puedas corregir los errores sin sobrecargar tu equipo con demasiados cambios.

Ejemplos de errores que Larastan detecta

A continuación, algunos ejemplos prácticos de cómo Larastan puede ayudarte:

• Método inexistente en un modelo: Si tratas de llamar a un método en un modelo que no existe, Larastan lo detectará:

• HasFactory sin tipado: Si utilizas por ejemplo el trait HasFactory y no le dice el tipo que utiliza la factoría, fallará:

• Tipos incorrectos en métodos: Si defines un método que debe retornar un tipo, pero en realidad devuelve otro, Larastan te avisará:

Integración con CI/CD

Larastan es una herramienta perfecta para integrarse con pipelines de integración continua (CI/CD). Puedes configurarlo para que se ejecute automáticamente en cada push o merge, y así asegurarte de que todo el equipo mantenga el estándar de calidad.

• GitHub Actions: Puedes configurar Larastan para que se ejecute en cada push con el siguiente yaml:

Conclusión

Larastan es una herramienta esencial para los desarrolladores Laravel que buscan mantener altos estándares de calidad en sus proyectos. Desde la detección de errores en etapas tempranas, hasta la mejora del rendimiento del equipo a través de la automatización, Larastan te ayudará a escribir mejor código. Empieza a usarlo hoy mismo, ajusta los niveles según tu progreso, y lleva tu código Laravel al siguiente nivel.

No dejes de aprender con nuestras rutas de aprendizaje:

• Ruta de PHP 8

• Ruta de Laravel 11