ldc-arcadia-api/documentation/Architecture/04-guide-nouveau-usecase.md

5 KiB

Guide Pratique : Créer un Nouveau Cas d'Usage - Arcadia API

Ce guide pas-à-pas accompagne un développeur dans la création d'un nouveau cas d'usage complet (ex: GET /api/v1/articles/{id}).


📋 Checklist en 5 Étapes

  1. Domaine (Domain\) : Définir l'Entité, les Value Objects et le Port (Interface).
  2. Infrastructure (Infra\) : Implémenter l'adaptateur Eloquent et enregistrer le binding.
  3. Application (Application\) : Créer le triplet Input, Output et ActionName (Use Case).
  4. Présentation (Presentation\) : Créer Presenter, View, Controller, Request et Response.
  5. Tests (tests/) : Rédiger les tests Unitaires, d'Intégration et de Feature (OpenAPI).

🛠️ Étape par Étape

1. Domaine : Le Port & le Modèle de Lecture / Entité

Définissez le modèle de lecture dans src/Domain/Models/Entities/Article.php :

namespace Domain\Models\Entities;

use Domain\Models\ValueObjects\ArticleId;
use Shared\DDD\Model\ReadModel;

/** @implements ReadModel<ArticleId> */
final readonly class Article implements ReadModel
{
    public function __construct(
        public ArticleId $id,
        public string $title,
    ) {}

    #[\Override]
    public function id(): ArticleId
    {
        return $this->id;
    }
}

Définissez l'interface dans src/Domain/Ports/Directories/ArticleDirectory.php :

namespace Domain\Ports\Directories;

use Domain\Models\Entities\Article;
use Domain\Models\ValueObjects\ArticleId;
use Shared\DDD\Port\Directory;

/** @extends Directory<ArticleId, Article> */
interface ArticleDirectory extends Directory
{
    public function find(ArticleId $id): ?Article;
}

2. Infrastructure : L'Adaptateur Eloquent

Implémentez l'interface dans src/Infra/Adapters/Directories/EloquentArticleDirectory.php :

namespace Infra\Adapters\Directories;

use Domain\Models\Entities\Article;
use Domain\Models\ValueObjects\ArticleId;
use Domain\Ports\Directories\ArticleDirectory;
use Infra\Database\Models\Article as EloquentArticle;

final class EloquentArticleDirectory implements ArticleDirectory
{
    #[\Override]
    public function find(ArticleId $id): ?Article
    {
        $model = EloquentArticle::query()->find($id->value);
        return $model ? $this->toDomain($model) : null;
    }

    private function toDomain(EloquentArticle $model): Article
    {
        return Article::hydrate(...);
    }
}

Enregistrez le binding dans src/Infra/Providers/DomainServiceProvider.php :

$this->app->bind(ArticleDirectory::class, EloquentArticleDirectory::class);

3. Application : Le Use Case

Dans src/Application/Arcadia/Usecase/Articles/Find/ :

Input.php :

namespace Application\Arcadia\Usecase\Articles\Find;

use Domain\Models\ValueObjects\ArticleId;
use Shared\DDD\Usecase\Input as BaseInput;

final readonly class Input implements BaseInput
{
    public function __construct(public ArticleId $id) {}
}

Output.php :

namespace Application\Arcadia\Usecase\Articles\Find;

use Domain\Models\Entities\Article;
use Shared\DDD\Usecase\Output as BaseOutput;

final readonly class Output implements BaseOutput
{
    public function __construct(public Article $article) {}
}

FindArticle.php :

namespace Application\Arcadia\Usecase\Articles\Find;

use Application\Arcadia\Exceptions\ArticleNotFoundException;
use Domain\Ports\Directories\ArticleDirectory;
use Shared\DDD\Usecase\Input as BaseInput;
use Shared\DDD\Usecase\Usecase;

/** @implements Usecase<Input, Output> */
final readonly class FindArticle implements Usecase
{
    public function __construct(private ArticleDirectory $directory) {}

    public function execute(BaseInput $input): Output
    {
        assert($input instanceof Input);

        $article = $this->directory->find($input->id);
        if ($article === null) {
            throw new ArticleNotFoundException($input->id);
        }

        return new Output($article);
    }
}

4. Présentation : Contrôleur & Presenter

  1. Presenter (ArticleShowPresenter) : convertit Output en ArticleShowView.
  2. Controller (ArticleShowController) : Single-action invokable exécutant UsecaseBuilder.
  3. Response (ArticleShowResponse) : formate la vue en JSON avec ArticleDto.
  4. Route dans routes/apiv1.php :
Route::get('/articles/{identifier}', ArticleShowController::class)
    ->name('articles.show');

5. Tests

  1. Unit Test (tests/Unit/Application/Arcadia/Usecase/Articles/FindArticleTest.php) : avec InMemoryArticleDirectory et Object Mother.
  2. Integration Test (tests/Integration/Infra/Adapters/Directories/EloquentArticleDirectoryTest.php) : test de la requête réelle sur base SQLite/MySQL de test.
  3. Feature Test (tests/Feature/Api/V1/Articles/ArticleShowTest.php) : test HTTP de bout en bout avec signature HMAC.
  4. OpenAPI Test (tests/Feature/OpenApi/V1/Articles/ArticleOpenApiTest.php) : conformité stricte au schéma openapi.yaml.