5 KiB
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
- Domaine (
Domain\) : Définir l'Entité, les Value Objects et le Port (Interface). - Infrastructure (
Infra\) : Implémenter l'adaptateur Eloquent et enregistrer le binding. - Application (
Application\) : Créer le tripletInput,OutputetActionName(Use Case). - Présentation (
Presentation\) : CréerPresenter,View,Controller,RequestetResponse. - 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
- Presenter (
ArticleShowPresenter) : convertitOutputenArticleShowView. - Controller (
ArticleShowController) : Single-action invokable exécutantUsecaseBuilder. - Response (
ArticleShowResponse) : formate la vue en JSON avecArticleDto. - Route dans
routes/apiv1.php:
Route::get('/articles/{identifier}', ArticleShowController::class)
->name('articles.show');
5. Tests
- Unit Test (
tests/Unit/Application/Arcadia/Usecase/Articles/FindArticleTest.php) : avecInMemoryArticleDirectoryetObject Mother. - Integration Test (
tests/Integration/Infra/Adapters/Directories/EloquentArticleDirectoryTest.php) : test de la requête réelle sur base SQLite/MySQL de test. - Feature Test (
tests/Feature/Api/V1/Articles/ArticleShowTest.php) : test HTTP de bout en bout avec signature HMAC. - OpenAPI Test (
tests/Feature/OpenApi/V1/Articles/ArticleOpenApiTest.php) : conformité stricte au schémaopenapi.yaml.