PHP/Laravel CONTEXT.md file

CONTEXT.md

Reglas de Desarrollo Proyectos PHP/Laravel

Versión: 1.0.0 Actualización: 2025-10-16 19:45

1. Fundamentos del Código y Calidad

• 1.1. Estándares de PHP
  • Utilizar siempre declare(strict_types=1); en la parte superior de cada archivo PHP.
  • Adherirse estrictamente a PSR-1, PSR-4 (autoloading) y PSR-12 (estilo de código).
  • Ejecutar php-cs-fixer y pint en el pipeline de integración continua (CI).
• 1.2. Tipado Estricto y Estructuras Inmutables
  • Tipar todas las propiedades de clase, argumentos de función y valores de retorno.
  • Preferir clases y propiedades readonly para los DTOs, objetos de valor y cualquier objeto que no deba mutar después de su creación.
• 1.3. Documentación Inteligente
  • Documentar con PHPDoc en inglés, enfocándose en el "porqué" y el "contexto" complejo, no en el "qué" (evitar comentarios redundantes).
  • Usar etiquetas de PHPStorm como @throws, @internal, @deprecated cuando sea relevante.

2. Arquitectura y Patrones de Diseño

• 2.1. Separación de Responsabilidades
  • Controladores: Delgados. Su única responsabilidad es manejar la solicitud HTTP y devolver una respuesta. Delegarán la lógica a otras capas.
  • Servicios & Actions: Contendrán la lógica de negocio cohesiva y reutilizable. Las "Actions" son clases únicas que realizan una única tarea (principio de responsabilidad única).
  • Form Requests: Utilizarlos siempre para la validación de entrada en controladores. Crear reglas personalizadas para lógica de validación compleja.
  • Livewire: Los componentes deben ser una capa de presentación. NUNCA contener lógica de negocio directa. Interactúan con Servicios o Actions.
• 2.2. Patrones para Complejidad y Escalabilidad
  • CQRS (Segregación de Responsabilidad de Consulta y Comando): Implementar para casos de uso complejos. Separar las operaciones de lectura (Queries) y escritura (Commands) en handlers dedicados.
  • DTOs (Objetos de Transferencia de Datos): Usar siempre para pasar datos entre capas (ej: de un FormRequest a un Service). Esto define un contrato claro e inmutable.
  • Repository Pattern (Opcional pero Recomendado): Implementar solo si se anticipa un cambio en el mecanismo de persistencia de datos (ej: de Eloquent a MongoDB) o para abstraer consultas extremadamente complejas. No usar como un proxy superfluo sobre Eloquent.
• 2.3. Gestión de Excepciones
  • Implementar un manejo centralizado de excepciones mediante el Handler de Laravel.
  • Crear excepciones de dominio personalizadas (ej: InsufficientFundsException, UserNotEligibleForSubscriptionException) para un control más granular y semántico.

3. Base de Datos y Eloquent

• 3.1. Diseño de Esquema y Migraciones
  • Estrategia de Identificadores:
    • id: Campo primario UUID (versión 7 recomendada por ser ordenada temporalmente).
    • code: Campo CHAR(8) único e indexado, que actuará como identificador público e inmutable.
  • Performance desde el Diseño: Índices en claves foráneas, code, y columnas de filtrado comunes.
  • Auditoría y Recuperación:
    • Implementar softDeletes y timestamps() en todas las tablas críticas.
    • Auditoría de Usuario: Implementar el paquete User Auditable for Laravel para el rastreo automático de created_by, updated_by y deleted_by.
  • Documentación: ->comment('Descripción del propósito de la tabla') obligatorio en cada migración.
• 3.2. Generación y Gestión del code
  • Generación Automática: El valor debe generarse de forma automática y síncrona durante el evento creating del modelo Eloquent usando el trait HasUniqueCode.
  • Algoritmo: Usar bin2hex(random_bytes(4)) para generar un string hexadecimal de 8 caracteres, garantizando aleatoriedad y unicidad.
  • Garantía de Unicidad: Implementar una lógica de "reintento" por si ocurre una colisión (extremadamente rara, pero posible).
  • Inmutabilidad: El campo debe ser declarado como protected $guarded = ['code']; o protected $fillable (excluyéndolo) en el modelo para prevenir su asignación masiva.
• 3.3. Mejores Prácticas de Eloquent
  • Route Binding: Sobrescribir getRouteKeyName() en el modelo para que las rutas utilicen code por defecto.
  • Pre-cargar relaciones con with() y withCount() para evitar el problema N+1.
  • Usar Eager Loading por defecto en relaciones que siempre se necesitan, definiendo $with en el modelo.
  • Ser consciente de la sobrecarga de hidratación de modelos. Para lecturas pesadas, considerar DB::table() o Eloquent Cursors.
  • Utilizar scopes locales y globales para encapsular lógica de consulta común.

4. Frontend y Experiencia de Usuario (Stack TALL)

• 4.1. Livewire
  • Mantener los componentes "tontos". La lógica de negocio reside en Servicios/Actions.
  • Utilizar propiedades con tipado (public string $name;).
  • Preferir la sintaxis de entangle de Alpine.js para una integración más limpia en lugar de depender excesivamente de wire:model.
• 4.2. Tailwind CSS
  • Aprovechar al máximo el sistema de diseño (colores, espaciado, breakpoints) definido en tailwind.config.js.
  • Extraer componentes repetitivos a componentes de Blade o clases de @apply para evitar la duplicación.
• 4.3. Vue.js (Para componentes de SPA o complejos)
  • Usar la Composition API con <script setup> para una mejor organización y reactividad.
  • Tipar props y eventos con TypeScript cuando sea posible.
  • Centralizar el estado compartido con Pinia.

5. Rendimiento, Escalabilidad y Producción

• 5.1. Caché Estratégico
  • Aplicar caché con etiquetas (Cache::tags()) para fragmentos de datos que son costosos de calcular y se invalidan en grupo (ej: users: {id}:posts).
  • Cachear respuestas de API completas o fragmentos de vistas cuando sea apropiado.
• 5.2. Procesamiento Asíncrono
  • Utilizar Queues y Jobs para cualquier operación que tome más de ~100ms (ej: envío de emails, procesamiento de archivos, llamadas a APIs externas).
• 5.3. Optimización de Servicios
  • Registrar Service Providers de manera diferida (defer: true) cuando sea posible para mejorar el tiempo de arranque de la aplicación.
• 5.4. Observabilidad (Production)
  • Implementar logging estructurado (con contexto).
  • Configurar monitoreo de métricas de performance (APM como Laravel Pulse, Clockwork, Telescope), health checks y alertas.

6. Seguridad por Defecto

• Validar y sanear toda la entrada del usuario (ya cubierto por Form Requests).
• Utilizar las herramientas de Laravel: CSRF protection, protección contra XSS (el escaping automático de Blade), SQL Injection (usar Eloquent/Query Builder).
• Aplicar el principio de menor privilegio en los gates y políticas.

7. Ciclo de Vida del Desarrollo

• 7.1. Testing Automatizado
  • Escribir tests desde el primer día. Seguir la Pirámide de Tests: muchos Unit Tests (para lógica de servicios/actions), menos Feature Tests (para flujos de usuario y APIs), y muy pocos End-to-End tests (para flujos críticos).
• 7.2. Control de Versiones
  • Adherirse estrictamente a Semantic Versioning (SemVer) para el versionado de la aplicación y de las APIs.
  • Mensajes de Commit: Seguir un estándar convencional. Ejemplo:
    • feat: agregar sistema de suscripciones con Stripe
    • fix: corregir cálculo de impuestos en el carrito
    • refactor: extraer lógica de pago a una Action dedicada
    • docs: actualizar README con guía de instalación