docs(architecture): add request lifecycle documentation for Arcadia API docs(architecture): add execution, transactions, and domain events documentation for Arcadia API docs(architecture): add guide for creating a new use case in Arcadia API docs(exceptions): summarize exception handling and HTTP status codes in Arcadia API docs(tests): outline testing strategy and conventions for Arcadia API style(openapi): correct description formatting in OpenAPI documentation chore: remove outdated exceptions documentation test: remove obsolete tests documentation
4.1 KiB
Exécution, Transactions & Événements de Domaine - Arcadia API
Ce document détaille le fonctionnement de l'exécuteur de cas d'usage (LaravelExecutor), de la gestion des transactions SQL et du cycle de vie des Événements de Domaine (Domain Events).
⚡ 1. Le Fluent Builder (UsecaseBuilder)
Pour garantir un typage strict et une exécution homogène à travers toute l'application, les Use Cases sont exécutés via un builder fluent :
$result = UsecaseBuilder::using($this->executor)
->do($this->usecase) // Le Use Case à exécuter
->from($input) // Le DTO Input entrant
->with(new CustomPresenter()) // (Optionnel) Le Presenter
->run(); // Exécute et retourne le View (ou l'Output)
Le builder garantit à la compilation (PHPStan Niveau 10) que les types d'Input, d'Output et de View concordent parfaitement.
🛡️ 2. Gestion des Transactions (Transactional)
Pour distinguer clairement les opérations de lecture (Query) des opérations d'écriture (Command) :
- Cas d'Usage en Lecture (Query) : N'implémente pas
Transactional. Exécuté directement sans overhead de transaction de base de données. - Cas d'Usage en Écriture (Command) : Implémente le marqueur
Shared\DDD\Usecase\Transactional.
namespace Application\Security\Usecases\CreateClient;
use Shared\DDD\Usecase\Transactional;
use Shared\DDD\Usecase\Usecase;
/** @implements Usecase<Input, Output> */
final readonly class CreateClient implements Transactional, Usecase
{
public function execute(BaseInput $input): Output
{
// Cette méthode sera automatiquement enveloppée dans
// DB::transaction(...) par le LaravelExecutor
}
}
📢 3. Événements de Domaine & Sécurité Post-Commit
Dans les architectures événementielles, un problème classique survient lorsqu'un événement est émis pendant une transaction SQL qui échoue ensuite (rollback) : les écouteurs ont déjà envoyé des notifications ou loggué des actions erronées.
Arcadia API résout ce problème via le pattern TransactionalDomainEventDispatcher :
sequenceDiagram
autonumber
participant UseCase as Cas d'Usage
participant Dispatcher as TransactionalDomainEventDispatcher (Buffer)
participant DB as Base de Données
participant Executor as LaravelExecutor
participant LaravelBus as Laravel Event Bus
Executor->>DB: DB::beginTransaction()
Executor->>UseCase: execute(input)
UseCase->>Dispatcher: dispatch(BrandCreated)
Note over Dispatcher: Événement stocké dans le buffer mémoire (non émis)
UseCase-->>Executor: Output
alt Succès de la Transaction
Executor->>DB: DB::commit()
Executor->>Dispatcher: release()
Dispatcher->>LaravelBus: dispatch(BrandCreated)
Note over LaravelBus: Les Listeners sont déclenchés après le commit garanti
else Exception / Rollback
Executor->>DB: DB::rollBack()
Executor->>Dispatcher: clear()
Note over Dispatcher: Le buffer est vidé, aucun événement fantôme n'est émis
end
💻 4. Comment Émettre un Événement dans le Domaine ?
Dans un service ou un Use Case de domaine, injectez simplement Shared\DDD\Event\DomainEventDispatcher :
namespace Domain\Services;
use Domain\Events\BrandCreated;
use Shared\DDD\Event\DomainEventDispatcher;
final readonly class BrandResolver
{
public function __construct(
private BrandRepository $brands,
private DomainEventDispatcher $dispatcher,
) {}
public function resolve(string $brandName): Brand
{
// Logique de résolution / création...
$brand = Brand::create(...);
$this->brands->persist($brand);
// Déclencher l'événement métier
$this->dispatcher->dispatch(new BrandCreated($brand));
return $brand;
}
}
Enregistrer un Écouteur (Listener)
Dans Infra\Providers\EventServiceProvider.php :
use Domain\Events\BrandCreated;
use Infra\Listeners\LogBrandCreated;
Event::listen(
BrandCreated::class,
LogBrandCreated::class,
);