PHP Insights: Métricas Objetivas para tu Código Laravel

Qué es PHP Insights

PHP Insights es una herramienta de análisis estático desarrollada por Nuno Maduro (creador de Pest Framework) que evalúa la calidad del código PHP en cuatro dimensiones simultáneas. Compatible con Laravel, Symfony y cualquier proyecto PHP moderno, no solo encuentra problemas sino que los corrige automáticamente con el flag --fix.

Lo que la diferencia de otras herramientas es su enfoque holístico: mientras PHPStan se centra en tipos y Pint en formato, PHP Insights evalúa arquitectura, complejidad, calidad y estilo en una sola pasada, generando un reporte visual que entiendes de un vistazo.

Las cuatro dimensiones que importan

Calidad de código

Analiza la distribución del código: qué porcentaje está en clases, funciones independientes, comentarios y scope global. Una puntuación superior al 80% indica código bien estructurado.

En proyectos Laravel, es normal tener algo de código global (helpers, archivos de rutas). Lo importante es que la mayoría esté organizado en clases. Si tu score está por debajo del 70%, probablemente tienes demasiado código procedural que deberías refactorizar.

Complejidad

La métrica más crítica para mantenibilidad. Mide la complejidad ciclomática: cuántos caminos diferentes puede tomar tu código. Ideal: menos de 5 por método. Un método con múltiples if, switch o condiciones anidadas es difícil de mantener, testear y entender.

Un score del 99% como el que conseguí significa que cada método hace una cosa y la hace bien. Esto no es casualidad: cuando usas patterns como Actions (una clase, una responsabilidad), la complejidad baja naturalmente. Si tu score está por debajo del 80%, tienes métodos que intentan hacer demasiado.

Arquitectura

Evalúa la organización estructural: uso correcto de clases, interfaces, traits, y la coherencia general del proyecto. Algunas sugerencias son opinionadas (como marcar todas las clases como final).

Mi proyecto tiene 82.4% aquí porque conscientemente no marco clases como final - necesito poder extenderlas para versionado. PHP Insights también sugiere no usar sufijos como "Interface" o "Abstract", pero prefiero la claridad explícita. Tu contexto decide qué sugerencias seguir.

Estilo

Verifica adherencia a PSR-12, convenciones de nomenclatura, mejores prácticas y potenciales problemas de seguridad. Consistencia en el código que facilita el trabajo en equipo y reduce la carga cognitiva al cambiar entre archivos.

Un 95% o más indica que cualquier desarrollador puede entrar a tu código y sentirse cómodo inmediatamente. No subestimes el valor de esto en equipos.

Instalación rápida

Analizar

Corregir automáticamente

Configuración práctica

El archivo config/insights.php permite personalizar los estándares:

También puedes deshabilitar insights específicos que no aplican a tu proyecto:

Automatización útil

Reportes históricos

Con estos datos JSON puedes crear dashboards, detectar tendencias o medir el impacto de refactorizaciones.

CI/CD Integration

En tu pipeline, añade PHP Insights como gate de calidad:

Si el código no cumple los mínimos, el deployment se detiene. Esto mantiene la deuda técnica bajo control.

Pre-commit hooks

Asegura calidad antes de cada commit:

Cuándo ignorar sugerencias (con criterio)

PHP Insights es opinionado, y eso está bien. Pero tu contexto manda:

• Clases finales: Si necesitas herencia para versionado o tu arquitectura requiere extensibilidad, ignora esta sugerencia. En bibliotecas públicas tiene sentido; en aplicaciones internas, menos.

• Sufijos en interfaces: UserServiceInterface es más explícito que UserService para la interface. Sí, es redundante. También es inmediatamente claro.

• Métodos largos en Resources: Los API Resources a veces necesitan más de 20 líneas para mapear datos complejos. Si cada línea tiene propósito claro, mantenlo.

• Constantes globales: En Laravel, defines constantes en config files. PHP Insights puede quejarse, pero es el patrón del framework.

Métricas reales y qué significan

En el proyecto API para biblioteca desarrollado con Claude Code que puedes ver en el vídeo al final del artículo conseguí lo siguiente sin esfuerzo:

• Código: 91.8% - Bien estructurado, mayoría en clases

• Complejidad: 99.2% - Métodos simples (1.28 ciclomática)

• Arquitectura: 82.4% - Penalizado por decisiones conscientes

• Estilo: 95.2% - Consistente y profesional

Estos números cuentan una historia: el código es mantenible, los métodos hacen una cosa cada uno, la arquitectura es sólida (aunque opinionada), y el estilo es consistente. No busques 100% en todo; busca balance y coherencia con tus decisiones.

Por qué importa ahora más que nunca

Con código generado por IA proliferando, herramientas como PHP Insights son críticas. La IA genera código funcional pero a menudo complejo, duplicado o inconsistente con el proyecto existente. PHP Insights mantiene estándares independientemente del origen del código.

Las métricas objetivas eliminan discusiones subjetivas en code reviews. "Este método es muy complejo" deja de ser opinión cuando la complejidad ciclomática es 15. Los problemas se detectan antes de ser costosos. El onboarding es más rápido con código consistente.

En equipos, establece mínimos no negociables. En proyectos personales, úsalo como coach de calidad. El código que escribes hoy lo mantendrás mañana.

Integración con otras herramientas

PHP Insights complementa perfectamente:

• PHPStan: Análisis estático profundo de tipos

• Rector: Refactoring automatizado y upgrades

• Pint: Formato de código con opiniones de Laravel

Úsalas juntas para máximo impacto.

Mi workflow: Rector para upgrades y mejores prácticas, PHP Insights para calidad, PHPStan para tipos, Pint para formato.

La calidad del código no es opcional. Son 5 minutos de configuración que se pagan en horas ahorradas de debugging, onboarding más rápido, y código del que te sentirás orgulloso.