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.
- 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
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);
}
}
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
);
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.
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.