Arquitectura Hexagonal con PHP: cómo escapar del monolito sin morir en el intento
Cuando llevas años trabajando con PHP en proyectos que crecen, llega un momento en que el código empieza a resistirse. Añadir una feature rompe tres cosas. Los tests no existen o no sirven. Todo está acoplado a todo.
Yo lo viví en primera persona. Y la solución fue la arquitectura hexagonal.
¿Qué es la arquitectura hexagonal?
También llamada Ports and Adapters, su idea central es simple: el dominio de tu aplicación no sabe nada del mundo exterior. No sabe si los datos vienen de una base de datos, de una API o de un fichero CSV. No sabe si la interfaz es web, CLI o una cola de mensajes.
Tu lógica de negocio vive en el centro. Todo lo demás son adaptadores intercambiables.
El antes y el después
En un proyecto legacy típico de PHP encuentras esto:
- Controladores con 500 líneas de lógica
- Queries SQL mezcladas con HTML
- Imposible testear sin levantar toda la aplicación
Con arquitectura hexagonal:
- Casos de uso aislados y testeables en milisegundos
- Puedes cambiar MySQL por PostgreSQL sin tocar el dominio
- Los tests unitarios son rápidos y fiables
Por dónde empezar
No hace falta reescribir todo. Yo recomiendo:
- Identifica un caso de uso concreto — una funcionalidad pequeña y bien definida
- Crea una interfaz (puerto) para cada dependencia externa
- Escribe el test primero (TDD) — te obliga a pensar en el contrato antes que en la implementación
- Implementa el adaptador — la conexión real a la base de datos, al email, al servicio externo
TDD como aliado
La arquitectura hexagonal y TDD se complementan perfectamente. Cuando el dominio no depende de nada externo, puedes testear con mocks simples y los tests corren en milisegundos.
Después de migrar el primer módulo así, no hay vuelta atrás.
¿Has aplicado arquitectura hexagonal en algún proyecto? ¿Qué dificultades encontraste? Cuéntalo en los comentarios.