En proyectos Laravel de cierto tamaño, entender cómo se relacionan las rutas, controladores, servicios, modelos, jobs, eventos, comandos y otros componentes puede convertirse en una tarea compleja. Esto ocurre especialmente en aplicaciones que han evolucionado durante años, han pasado por distintos equipos de desarrollo o tienen una arquitectura con múltiples capas.
Para estos casos, herramientas como Laravel Brain pueden resultar muy útiles. Se trata de un paquete para Laravel orientado al entorno de desarrollo que analiza una aplicación y genera una representación visual de su arquitectura mediante un grafo interactivo.
Su objetivo principal es claro: ayudar al equipo técnico a comprender de forma rápida el ciclo de vida completo de una petición dentro de una aplicación Laravel.
¿Qué es Laravel Brain?
Laravel Brain es una herramienta de análisis estático para aplicaciones Laravel. Una vez instalada, permite escanear el código del proyecto y generar una visualización interactiva en la que se representan los principales elementos de la aplicación.
Entre los elementos que puede detectar se encuentran:
- Rutas HTTP.
- Middlewares.
- Controladores y acciones.
- Servicios y repositorios.
- Modelos Eloquent.
- Relaciones entre modelos.
- Jobs.
- Eventos.
- Comandos Artisan.
- Tareas programadas.
- Canales de broadcasting.
- Paneles y recursos de Filament.
La herramienta se define como un sistema para visualizar el ciclo completo de una petición Laravel mediante un grafo interactivo, conectando rutas, controladores, servicios, modelos, jobs, eventos, comandos y canales.
Instalación básica
Laravel Brain está pensado para instalarse como dependencia de desarrollo, no como dependencia de producción:
composer require --dev laramint/laravel-brainDespués, se puede ejecutar el análisis del proyecto con:
php artisan brain:scanUna vez finalizado el escaneo, la herramienta genera los archivos JSON necesarios en storage/app/laravel-brain/ y permite abrir el visor desde la ruta:
/_laravel-brainEl comando brain:scan analiza el código y escribe los datos del grafo en storage/app/laravel-brain/.
Principales funcionalidades
Una de las funcionalidades más interesantes de Laravel Brain es la trazabilidad del ciclo de vida de una ruta. A partir de una ruta concreta, la herramienta puede mostrar cómo se conecta con su controlador, qué métodos se ejecutan, qué servicios intervienen y qué modelos o consultas se utilizan.
Esto resulta especialmente útil en tareas como:
- Auditorías técnicas de aplicaciones existentes.
- Mantenimiento evolutivo.
- Incorporación de nuevos desarrolladores a un proyecto.
- Refactorización de código heredado.
- Detección de clases demasiado grandes o complejas.
- Revisión de dependencias internas.
- Documentación técnica de proyectos Laravel.
Además, Laravel Brain incluye detección de clases grandes, cálculo de complejidad ciclomática, visualización de relaciones Eloquent, diagramas de secuencia, exportación a Mermaid y PNG, y modo de observación para reanalizar automáticamente el proyecto cuando cambian archivos PHP.
Integración con inteligencia artificial
Un punto diferencial de Laravel Brain es que no se limita a mostrar un grafo visual. También permite exportar contexto optimizado para herramientas de inteligencia artificial.
La herramienta puede generar un bloque de contexto en Markdown o JSON a partir de un nodo o ruta concreta, incluyendo información como:
- Ruta y middleware.
- Cadena de llamadas.
- Puntos de complejidad.
- Operaciones de base de datos.
- Fragmentos de código fuente.
- Dependencias backend y frontend.
Este contexto puede copiarse y utilizarse en herramientas como ChatGPT, Claude, Cursor, GitHub Copilot, Windsurf o asistentes similares. Según la documentación del proyecto, la exportación es determinista: el mismo escaneo y el mismo nodo producen siempre la misma salida.
También permite generar archivos de reglas para distintos asistentes de programación, como CLAUDE.md, .cursor/rules/laravel-brain.mdc, .github/copilot-instructions.md o AGENTS.md.
Esto puede ser especialmente interesante en equipos que ya utilizan IA como apoyo al desarrollo, porque permite que el asistente trabaje con información real de la arquitectura del proyecto y no únicamente con fragmentos aislados de código.
Uso en proyectos con Filament
Laravel Brain también incorpora soporte para Filament PHP, una de las herramientas más utilizadas actualmente para construir paneles de administración en Laravel.
Puede detectar paneles, recursos, páginas, widgets y relation managers, y trazar llamadas desde métodos de páginas Filament igual que lo hace con acciones de controladores.
Esto es relevante porque muchos proyectos Laravel modernos concentran gran parte de su lógica de negocio en paneles internos, backoffices o herramientas de administración construidas con Filament.
Pruebas de carga sobre rutas
Otra característica interesante es la integración con laramint/laravel-stress, que permite lanzar pruebas de carga sobre rutas seleccionadas desde la propia interfaz visual.
Desde un nodo de tipo ruta, se pueden configurar parámetros como:
- Número de peticiones.
- Concurrencia.
- Cabeceras.
- Cuerpo de la petición.
- Timeout.
- Distribución de códigos de estado.
- Métricas de tiempo como p50, p95 o p99.
El paquete incluye validaciones para restringir estas pruebas a entornos de desarrollo o redes privadas, lo que refuerza su orientación como herramienta local de análisis técnico.
Seguridad: solo para desarrollo
Laravel Brain debe utilizarse con precaución y siempre como herramienta de desarrollo.
El paquete registra rutas bajo el prefijo /_laravel-brain, desde las que se puede acceder al visor, a los archivos del grafo, al código fuente y a otras operaciones de análisis. La documentación lista estas rutas, incluyendo endpoints para ver código fuente, lanzar escaneos, exportar contexto y generar reglas para asistentes de IA.
El propio ServiceProvider del paquete evita registrar rutas y comandos si la aplicación no se encuentra en entorno local, lo cual es una decisión adecuada desde el punto de vista de seguridad.
Aun así, en cualquier entorno accesible desde red, conviene proteger estas rutas mediante middleware, autenticación o restricciones adicionales. La documentación también recomienda protegerlas si se instalan en un entorno no productivo accesible por red.
Requisitos técnicos
Laravel Brain requiere:
- PHP 8.0 o superior.
- Laravel 9, 10, 11, 12 o 13.
- Composer.
Estos requisitos aparecen tanto en el README como en el archivo composer.json del repositorio.
¿En qué casos puede ser útil?
En SOLUCIONEX trabajamos habitualmente con proyectos Laravel y Symfony en los que la mantenibilidad, la claridad arquitectónica y la calidad del código son factores clave.
Una herramienta como Laravel Brain puede aportar valor en escenarios como los siguientes:
- Auditoría inicial de un proyecto Laravel: Cuando se recibe un proyecto existente, el primer reto suele ser entender cómo está organizado. Laravel Brain permite obtener una primera visión estructural de la aplicación sin tener que revisar manualmente todos los controladores, rutas y servicios.
- Mantenimiento evolutivo: Antes de modificar una funcionalidad crítica, es importante saber qué piezas intervienen. El grafo ayuda a identificar dependencias, clases relacionadas y posibles efectos colaterales.
- Refactorización: La detección de clases grandes, rutas complejas o puntos con alta complejidad ciclomática puede ayudar a priorizar tareas de mejora técnica.
- Documentación técnica: Los grafos, diagramas y exportaciones pueden servir como apoyo para documentar proyectos, especialmente cuando se trabaja con clientes, equipos externos o nuevos desarrolladores.
- Uso combinado con IA: La exportación de contexto para asistentes de IA permite trabajar con una visión más completa del proyecto, reduciendo el riesgo de que el asistente proponga cambios desconectados de la arquitectura real.
Conclusión
Laravel Brain es una herramienta muy interesante para equipos que trabajan con aplicaciones Laravel de tamaño medio o grande. Su principal aportación es convertir una estructura de código compleja en una representación visual más fácil de entender.
No sustituye a una revisión técnica profunda ni a buenas prácticas de arquitectura, testing o documentación, pero sí puede acelerar mucho el diagnóstico inicial de un proyecto y facilitar tareas de mantenimiento, refactorización y análisis.
Para equipos que ya trabajan con asistentes de inteligencia artificial, su capacidad para generar contexto estructurado añade además una utilidad adicional: permitir que estas herramientas comprendan mejor la arquitectura real de la aplicación.
En definitiva, Laravel Brain puede convertirse en una herramienta de apoyo muy valiosa para mejorar la comprensión, documentación y mantenibilidad de proyectos Laravel.
