DEV Community

Gonzalo López
Gonzalo López

Posted on Originally published at blogprog.gonzalolopez.es

laravel + ddd + arquitectura hexagonal explicado de forma sencilla

laravel + ddd + arquitectura hexagonal explicado de forma sencilla

El desarrollo tradicional con Laravel suele basarse en controladores con mucha lógica, modelos Eloquent que concentran múltiples responsabilidades y reglas de negocio mezcladas con detalles técnicos. La combinación de Domain-Driven Design, o DDD, y Arquitectura Hexagonal ofrece una alternativa más limpia, escalable y mantenible.A continuación se explica de manera práctica cómo aplicar estos conceptos en Laravel, con ejemplos claros y código real. Conceptos básicos Domain-Driven Design, o DDD, consiste en modelar el software alrededor del negocio, o el dominio, en lugar de alrededor de la base de datos o del framework. Arquitectura Hexagonal separa el núcleo de la aplicación de todo lo externo: base de datos, frameworks, APIs u otros sistemas. El principio fundamental es el siguiente: El dominio, o reglas de negocio, no debe conocer detalles de Laravel, Eloquent, MySQL ni HTTP. Esta separación aporta: Mayor facilidad para realizar pruebas. Mejor mantenibilidad a medida que el proyecto crece. Posibilidad de cambiar de base de datos o incluso de framework sin reescribir la lógica de negocio. Estructura de carpetas recomendada Se recomienda crear una carpeta "src", o mantener la carpeta "app" si se prefiere, organizada de la siguiente manera: src/ └── Admin/ ← Bounded Context (contexto delimitado) └── User/ ← Dominio / Módulo ├── Domain/ ← Capa más interna (pura) │ ├── Entity/ │ │ └── User.php │ ├── ValueObject/ │ │ ├── UserId.php │ │ ├── UserName.php │ │ └── UserEmail.php │ └── Contract/ ← Puertos (interfaces) │ └── UserRepositoryInterface.php │ ├── Application/ ← Casos de uso │ ├── CreateUserUseCase.php │ └── GetUserByIdUseCase.php │ └── Infrastructure/ ← Adaptadores (Laravel, Eloquent, etc.) ├── Persistence/ │ └── EloquentUserRepository.php └── Http/ └── Controllers/ └── UserController.php Es posible tener varios Bounded Contexts, como Admin, Ventas, Productos, etc. Capa de Dominio En esta capa solo se utiliza PHP puro. No se incluyen referencias a "Illuminate...." Value Objects Son clases inmutables que encapsulan un valor junto con sus reglas de validación. // src/Admin/User/Domain/ValueObject/UserEmail.php final class UserEmail { private string $value; public function __construct(string $email) { if (!filter_var($email, FILTER_VALIDATE_EMAIL)) { throw new \InvalidArgumentException('Email no válido'); } $this->value = strtolower($email); } public function value(): string { return $this->value; } } Entidad // src/Admin/User/Domain/Entity/User.php final class User { public function __construct( private UserId $id, private UserName $name, private UserEmail $email ) {} public function id(): UserId { return $this->id; } public function name(): UserName { return $this->name; } public function email(): UserEmail { return $this->email; } } Puerto o Interfaz del repositorio // src/Admin/User/Domain/Contract/UserRepositoryInterface.php interface UserRepositoryInterface { public function save(User $user): void; public function findById(UserId $id): ?User; } Capa de Aplicación Esta capa orquesta la lógica sin depender de Laravel. // src/Admin/User/Application/CreateUserUseCase.php final class CreateUserUseCase { public function __construct( private UserRepositoryInterface $repository ) {} public function execute(string $id, string $name, string $email): void { $user = new User( new UserId($id), new UserName($name), new UserEmail($email) ); $this->repository->save($user); } } El caso de uso recibe datos primitivos, construye los Value Objects y la entidad, delegando la persistencia en el repositorio. Capa de Infraestructura En esta capa se utilizan las herramientas de Laravel, como Eloquent, controladores, etc. Adaptador del repositorio // src/Admin/User/Infrastructure/Persistence/EloquentUserRepository.php final class EloquentUserRepository implements UserRepositoryInterface { public function save(User $user): void { UserModel::updateOrCreate( ['id' => $user->id()->value()], [ 'name' => $user->name()->value(), 'email' => $user->email()->value(), ] ); } public function findById(UserId $id): ?User { $model = UserModel::find($id->value()); if (!$model) { return null; } return new User( new UserId($model->id), new UserName($model->name), new UserEmail($model->email) ); } } Controlador // src/Admin/User/Infrastructure/Http/Controllers/UserController.php final class UserController extends Controller { public function store(Request $request, CreateUserUseCase $useCase) { $useCase->execute( id: (string) Str::uuid(), name: $request->input('name'), email: $request->input('email') ); return response()->json(['message' => 'Usuario creado'], 201); } } Conexión de componentes o Inyección de dependencias En un Service Provider se realiza el enlace: $this->app->bind( UserRepositoryInterface::class, EloquentUserRepository::class ); Laravel se encarga de resolver las dependencias automáticamente. Flujo completoLlega una petición HTTP al controlador. El controlador invoca el caso de uso. El caso de uso crea la entidad y los Value Objects, aplicando las reglas de negocio. El caso de usollama al repositorio a través de su interfaz. La implementación concreta, en este caso Eloquent realiza la persistencia en la base de datos. El dominio permanece completamente ajeno a la existencia de Laravel. Recomendaciones prácticas Comenzar con un único módulo, por ejemplo, usuario o producto. No pretender aplicar DDD de forma perfecta desde el inicio; avanzar de manera progresiva. Utilizar Value Objects solo en aquellos casos en los que aporten validación o significado real. Mantener los casos de uso pequeños y enfocados, un caso de uso representa una única intención. Los tests unitarios del dominio y de los casos de uso resultan considerablemente más sencillos con esta estructura.

Top comments (0)