Análisis: Principios de Good Code en Laravel Contexto Se plantean seis reglas fundamentales basadas en el Laravel Starter Kit de Nuno Maduro. El desafío no es solo aplicarlas en proyectos nuevos, sino integrar esta filosofía en proyectos existentes. Cambio de paradigma fundamental Tesis central : La flexibilidad de Laravel no debe confundirse con libertad para escribir código descuidado. La strictness no es un obstáculo, es un acelerador. Problema identificado : Desarrolladores que utilizan la "magia" de Laravel como excusa para evitar tipos, tests incompletos y análisis estático. Análisis de los seis principios Principio 1: Cobertura de tipos al 100% Qué implica : pest --type-coverage --min=100 Análisis crítico : Este principio fuerza la intencionalidad en cada variable y parámetro. La cobertura de tipos no es documentación, es contrato. Ventajas : Reduce bugs de integración en un 60-70% según estudios empíricos El IDE se convierte en aliado activo Refactorizaciones seguras sin miedo Desventajas : Requiere tiempo inicial significativo en proyectos legacy Puede generar fricción con equipos acostumbrados a PHP dinámico Arrays asociativos complejos necesitan DTOs o Value Objects Implementación gradual en proyectos existentes : Activar cobertura de tipos sin bloquear CI inicialmente Establecer baseline actual Regla: nuevo código debe tener 100% de cobertura Refactorizar módulos críticos primero Incrementar baseline mensualmente Relación con SOLID : Dependency Inversion Principle se beneficia directamente. Interfaces tipadas fuerzan contratos claros. Principio 2: PHPStan en nivel MAX Qué implica : Análisis estático sin concesiones. PHPStan nivel 9 (MAX) detecta: Dead code Posibles nulls no manejados Tipos incompatibles en operaciones Propiedades no inicializadas Análisis crítico : El nivel MAX expone deuda técnica oculta. No es ego, es disciplina. Ventajas : Detecta bugs antes de testing Complementa cobertura de tipos Fuerza a pensar en edge cases Desventajas : Output inicial puede ser abrumador en proyectos legacy Requiere aprendizaje de sus reglas Algunas reglas pueden requerir baseline temporal Implementación gradual : # Paso 1: Generar baseline vendor/bin/phpstan analyse --generate-baseline # Paso 2: Subir nivel progresivamente # phpstan.neon parameters: level: 5 # Empezar aquí, no en MAX # Paso 3: Incrementar cada sprint # Sprint 1: nivel 5 # Sprint 2: nivel 6 # Sprint N: nivel 9 (MAX) Relación con Testing : PHPStan reduce la necesidad de ciertos tests unitarios. Si el tipo system garantiza que nunca pasarás null a una función, no necesitas testearlo. Principio 3: Cobertura de tests al 100% Qué implica : pest --parallel --coverage --exactly=100.0 Análisis crítico : La palabra clave es "exactly". No 99.8%. Exactamente 100%. Ventajas : Elimina código muerto rápidamente Tests paralelos aceleran feedback loop Confianza absoluta en refactorizaciones Desventajas : 100% coverage no garantiza calidad de tests Puede incentivar tests superficiales solo por métricas Requiere infraestructura para tests paralelos confiables La trampa del 100% : Cobertura de líneas no es cobertura de comportamiento. Un test puede ejecutar línea sin validar su lógica. Mejor enfoque : Combinar cobertura de líneas con mutation testing: # Infection PHP vendor/bin/infection --min-msi=80 Implementación gradual : Identificar módulos críticos de negocio Llevar estos a 100% primero Expandir a módulos de soporte Mantener 100% en código nuevo desde día 1 Relación con SOLID : Single Responsibility Principle facilita testing. Clases con una responsabilidad son más fáciles de testear al 100%. Principio 4: Formateo estricto automático Qué implica : Laravel Pint + Prettier eliminan decisiones de estilo. Análisis crítico : Este es el principio más subestimado. No es cosmético, es cognitivo. Ventajas : Cero tiempo en code reviews discutiendo formato Diffs limpios enfocados en lógica Onboarding más rápido Desventajas : Puede generar diffs masivos en primera aplicación Requiere consenso del equipo Algunos desarrolladores lo perciben como pérdida de "estilo personal" Implementación inmediata : # Aplicar una sola vez ./vendor/bin/pint # Pre-commit hook # .git/hooks/pre-commit ./vendor/bin/pint --dirty Este principio no tiene desventajas técnicas reales . Solo resistencia humana. Principio 5: Control del entorno en tests Qué implica : Congelar tiempo Fake HTTP calls Forzar HTTPS en tests Análisis crítico : Tests deben ser deterministas. El mundo exterior es no determinista. Ventajas en Laravel : // Determinismo temporal Carbon::setTestNow('2025-01-15 10:00:00'); // Aislamiento de HTTP Http::fake([ 'api.external.com/*' => Http::response(['data' => 'fake'], 200) ]); Desventajas : Requiere disciplina para identificar qué fakear Tests de integración reales siguen siendo necesarios Puede ocultar problemas de configuración real Implementación : Separar claramente: Unit tests: todo fakeado Integration tests: servicios reales en ambiente controlado E2E tests: flujo completo Relación con Testing : Este principio hace posible el 100% de cobertura. Sin él, tests son frágiles y lentos. Principio 6: CI como senior engineer más estricto Qué implica : GitHub Actions ejecutando: Pint (formato) Rector (refactoring automático) PHPStan (análisis estático) Pest (tests) Lint (sintaxis) Análisis crítico : CI no es opcional. Es el guardián de calidad 24/7. Ventajas : Feedback inmediato en PRs Imposible mergear código que rompe estándares Documentación viva de estándares del equipo Desventajas : Requiere configuración inicial Puede ralentizar merges si CI es lento Falsos positivos pueden frustrar Implementación óptima : # .github/workflows/tests.yml name: Tests on: [push, pull_request] jobs: tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: 8.3 coverage: xdebug - name: Install Dependencies run: composer install - name: Run Pint run: ./vendor/bin/pint --test - name: Run PHPStan run: ./vendor/bin/phpstan analyse - name: Run Pest run: ./vendor/bin/pest --parallel --coverage --min=100 Estrategia gradual : Empezar solo con tests Agregar Pint Agregar PHPStan con baseline Subir nivel progresivamente El error fundamental identificado Cita clave : "Confundir flexibilidad con libertad" Laravel es flexible en arquitectura, no en disciplina. La flexibilidad es para resolver problemas de negocio, no para evitar buenas prácticas. Análisis del error Manifestaciones comunes : Arrays asociativos en lugar de DTOs Métodos sin type hints "porque total funciona" Tests solo de happy path "Lo arreglo después" que nunca llega Costo real : Debugging que consume 40-60% del tiempo de desarrollo Bugs en producción que dañan reputación Refactorizaciones imposibles sin miedo Onboarding lento de nuevos desarrolladores Roadmap de implementación en proyectos existentes Fase 1: Evaluación y baseline (Sprint 1-2) Acciones : Ejecutar PHPStan nivel 5 con baseline Medir cobertura de tipos actual Medir cobertura de tests actual Aplicar Pint una sola vez Documentar estado actual Entregable : Documento con métricas actuales y brechas. Fase 2: Quick wins (Sprint 3-4) Acciones : Configurar Pint en pre-commit hook Implementar CI básico (tests + Pint) Nueva regla: código nuevo debe cumplir 100% tipos y tests Identificar 3 módulos críticos para refactorizar Entregable : CI funcionando, código nuevo bajo estándares. Fase 3: Refactoring progresivo (Sprint 5-12) Acciones : Refactorizar módulos críticos a 100% tipos y tests Subir PHPStan un nivel cada 2 sprints Reducir baseline de PHPStan 10% cada sprint Code reviews enfocados en principios Entregable : Módulos críticos bajo estándares, PHPStan nivel 7-8. Fase 4: Consolidación (Sprint 13+) Acciones : PHPStan nivel MAX sin baseline 100% cobertura en todo el proyecto Mutation testing implementado Documentación de arquitectura Entregable : Proyecto completamente bajo estándares. Comparación: Enfoque tradicional vs Good Code Aspecto Tradicional Good Code Types Opcional Obligatorio 100% Tests "Lo importante" 100% exacto Análisis estático Si da tiempo PHPStan MAX Formato Discutido en CR Automatizado CI Tests básicos Guardián completo Velocidad inicial Rápida Moderada Velocidad sostenida Decreciente Creciente Confianza deployment Rezar Saber Relación con SOLID Single Responsibility Principle Clases con una responsabilidad son más fáciles de tipar y testear al 100%. Open/Closed Principle Interfaces tipadas garantizan extensión sin modificación. Liskov Substitution Principle PHPStan MAX detecta violaciones automáticamente. Interface Segregation Principle Cobertura de tipos fuerza interfaces específicas. Dependency Inversion Principle Type hints en constructores formalizan inversión de dependencias. Consideraciones finales Pregunta clave ¿Es esto overkill para proyectos pequeños? Respuesta : Depende del horizonte temporal. Si el proyecto vivirá más de 6 meses, no es overkill. Es inversión. Obstáculos reales Resistencia del equipo : Cambio cultural requiere tiempo Tiempo inicial : Primera implementación consume sprints Falsa sensación de lentitud : Strictness se siente lenta hasta que debuggear se vuelve raro Beneficios medibles Reducción de bugs en producción: 60-80% Tiempo de onboarding: -50% Confianza en refactoring: +200% Velocidad de features (después de 3 meses): +30% Conclusión La filosofía de Good Code no es una lista de herramientas. Es un cambio de mentalidad: de "funciona ahora" a "funciona siempre". El starter kit de Nuno Maduro no es el objetivo. Es el ejemplo de que es posible. La meta es internalizar estos principios hasta que escribir código sin tipos, sin tests o sin análisis estático se sienta antinatural. Tesis final : Strictness no es burocracia. Es la única forma conocida de escalar complejidad sin colapsar en caos. Recursos Laravel Starter Kit de Nuno Maduro PHPStan Documentation Pest PHP Documentation Laravel Pint Documentation Principios SOLID aplicados a Laravel - Opinated Agradecimientos a Vishal Rajpurohit por su hilo conductor Aviso Esta documentación y su contenido, no implica que funcione en tu caso o determinados casos. También implica que tienes conocimientos sobre lo que trata, y que en cualquier caso tienes copias de seguridad. El contenido el contenido se entrega, tal y como está, sin que ello implique ningún obligación ni responsabilidad por parte de Castris Si necesitas soporte profesional puedes contratar con Castris soporte profesional .