5 min. de lectura (aproximado)

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.

  1. El controlador invoca el caso de uso.
  2. El caso de uso crea la entidad y los Value Objects, aplicando las reglas de negocio.
  3. El caso de usollama al repositorio a través de su interfaz.
  4. 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.