Domain-Driven Design (DDD) y Clean Architecture en PHP 8.4 y Symfony 7.2

Cuando los monolitos corporativos crecen durante varios años, el fallo arquitectónico más recurrente es el acoplamiento con el framework: reglas de negocio mezcladas en entidades del ORM, controladores que gobiernan transacciones de base de datos y esquemas relacionales que dictan la forma de los conceptos del negocio.

En sectores de alta exigencia transaccional —como fondos de pensiones, banca o sistemas logísticos— esta degradación genera corrupción silenciosa de datos y resistencia del equipo a refactorizar.

Te comparto el patrón arquitectónico exacto que implemento para aplicar Domain-Driven Design (DDD) y Clean Architecture en proyectos con PHP 8.4 y Symfony 7.2.

1. Estructura de Directorios: Bounded Contexts Aislados

En lugar de agrupar el código por capas técnicas genéricas (Controller/, Entity/, Repository/), divide el sistema en contextos acotados (Bounded Contexts). Dentro de cada uno, establece un flujo de dependencias unidireccional estricto:

src/
├── PensionManagement/                  # Bounded Context
│   ├── Domain/                         # 100% Agnóstico al Framework
│   │   ├── Model/                      # Agregados, Entidades y Value Objects
│   │   │   ├── PensionCalculation.php
│   │   │   └── PensionBeneficiary.php
│   │   ├── ValueObject/
│   │   │   ├── CurrencyAmount.php
│   │   │   └── SocialSecurityNumber.php
│   │   ├── Event/
│   │   │   └── PensionSettledEvent.php
│   │   └── Repository/
│   │       └── PensionCalculationRepositoryInterface.php
│   ├── Application/                    # Casos de Uso y Handlers
│   │   ├── Command/
│   │   │   ├── CalculatePensionCommand.php
│   │   │   └── CalculatePensionHandler.php
│   │   └── Query/
│   │       ├── GetBeneficiaryStatementQuery.php
│   │       └── GetBeneficiaryStatementHandler.php
│   └── Infrastructure/                 # Adaptadores de Framework y Base de Datos
│       ├── Persistence/
│       │   ├── DoctrinePensionCalculationRepository.php
│       │   └── Mapping/                # Mapeo XML o PHP (cero anotaciones en entidades)
│       └── Web/
│           └── Controller/
│               └── PensionCalculationController.php

La Regla Inviolable

El directorio Domain no debe importar clases de Symfony\*, Doctrine\* ni librerías externas. Solo utiliza tipos nativos de PHP 8.4 y primitivas estándar del lenguaje.

2. Modelado de Agregados en PHP 8.4 Puro

La raíz del agregado (Aggregate Root) protege sus invariantes de negocio. No puede instanciarse en un estado inválido ni mutar sus propiedades mediante setters públicos:

<?php

declare(strict_types=1);

namespace App\PensionManagement\Domain\Model;

use App\PensionManagement\Domain\ValueObject\CurrencyAmount;
use App\PensionManagement\Domain\ValueObject\SocialSecurityNumber;
use App\PensionManagement\Domain\Event\PensionSettledEvent;
use InvalidArgumentException;

final class PensionCalculation
{
    private string $id;
    private SocialSecurityNumber $beneficiarySsn;
    private CurrencyAmount $accruedAmount;
    private string $status;
    private array $recordedEvents = [];

    private function __construct(
        string $id,
        SocialSecurityNumber $beneficiarySsn,
        CurrencyAmount $initialAmount
    ) {
        $this->id = $id;
        $this->beneficiarySsn = $beneficiarySsn;
        $this->accruedAmount = $initialAmount;
        $this->status = 'DRAFT';
    }

    public static function create(
        string $id,
        SocialSecurityNumber $beneficiarySsn,
        CurrencyAmount $initialAmount
    ): self {
        return new self($id, $beneficiarySsn, $initialAmount);
    }

    public function settle(CurrencyAmount $finalIndexedAmount): void
    {
        if ($this->status !== 'DRAFT') {
            throw new InvalidArgumentException('Solo los cálculos en borrador pueden liquidarse.');
        }

        $this->accruedAmount = $finalIndexedAmount;
        $this->status = 'SETTLED';

        $this->recordedEvents[] = new PensionSettledEvent(
            $this->id,
            $this->beneficiarySsn->value(),
            $this->accruedAmount->cents()
        );
    }

    public function pullEvents(): array
    {
        $events = $this->recordedEvents;
        $this->recordedEvents = [];
        return $events;
    }
}

Aspectos clave:

• Cero anotaciones o atributos de Doctrine dentro de la clase de dominio.
• Los Value Objects (CurrencyAmount, SocialSecurityNumber) validan formato y precisión aritmética en su constructor.
• Los eventos de dominio se registran internamente y se despachan de forma atómica al persistir el agregado.

3. CQRS y Límites Transaccionales con Symfony Messenger

Nunca ejecutes transacciones de negocio complejas en los controladores. Encapsula las mutaciones en objetos de comando inmutables despachados mediante Symfony Messenger:

<?php

declare(strict_types=1);

namespace App\PensionManagement\Application\Command;

final readonly class CalculatePensionCommand
{
    public function __construct(
        public string $calculationId,
        public string $socialSecurityNumber,
        public int $amountInCents,
        public string $currency = 'EUR'
    ) {}
}

Y el handler de aplicación delimita la frontera transaccional:

<?php

declare(strict_types=1);

namespace App\PensionManagement\Application\Command;

use App\PensionManagement\Domain\Model\PensionCalculation;
use App\PensionManagement\Domain\ValueObject\SocialSecurityNumber;
use App\PensionManagement\Domain\ValueObject\CurrencyAmount;
use App\PensionManagement\Domain\Repository\PensionCalculationRepositoryInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final readonly class CalculatePensionHandler
{
    public function __construct(
        private PensionCalculationRepositoryInterface $repository
    ) {}

    public function __invoke(CalculatePensionCommand $command): void
    {
        $ssn = SocialSecurityNumber::fromString($command->socialSecurityNumber);
        $amount = CurrencyAmount::fromCents($command->amountInCents, $command->currency);

        $calculation = PensionCalculation::create(
            $command->calculationId,
            $ssn,
            $amount
        );

        $calculation->settle($amount);

        // El repositorio persiste la entidad y despacha los eventos registrados
        $this->repository->save($calculation);
    }
}

4. Mapeo de Doctrine sin Contaminar el Dominio

Para conservar el dominio desacoplado, define los mapeos de base de datos en archivos XML dentro de src/PensionManagement/Infrastructure/Persistence/Mapping/:

<?xml version="1.0" encoding="UTF-8"?>
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping">
    <entity name="App\PensionManagement\Domain\Model\PensionCalculation" table="pension_calculations">
        <id name="id" type="string" length="36" />
        <field name="status" type="string" length="32" />
        <embedded name="beneficiarySsn" class="App\PensionManagement\Domain\ValueObject\SocialSecurityNumber" use-column-prefix="false" />
        <embedded name="accruedAmount" class="App\PensionManagement\Domain\ValueObject\CurrencyAmount" use-column-prefix="false" />
    </entity>
</doctrine-mapping>

Con este desacoplamiento, cualquier actualización mayor de Symfony o Doctrine no impacta tu lógica de negocio.

5. Validación y Métricas en Producción

Este diseño no es una propuesta teórica. Lo implementé en la Plataforma Corporativa Francesa de Fondos de Pensiones, procesando cálculos de previsión social:

• +99.98% de disponibilidad operativa: Cero caídas ocasionadas por violaciones en límites de dominio.
• Cero incidentes de corrupción transaccional: La validación de invariantes en la raíz del agregado impidió mutaciones inconsistentes.
• Reducción del 60% en tiempos de consulta: La separación estricta de comandos de escritura y consultas de lectura (CQRS) optimizó los cálculos financieros más pesados.

Conclusión Pragmática

Los frameworks son mecanismos de entrega, no tu arquitectura. Trata a Symfony como un adaptador de infraestructura y resguarda tu dominio con agregados en PHP 8.4 puro y handlers CQRS para garantizar mantenibilidad a largo plazo.