first commit

src/Post/PostServiceInterface.php

@@ -0,0 +1,119 @@
+<?php
+declare(strict_types=1);
+
+namespace App\Post;
+
+use App\Shared\Exception\NotFoundException;
+
+/**
+ * Contrat du service de gestion des articles.
+ *
+ * Permet de mocker le service dans les tests unitaires sans dépendre
+ * de la classe concrète finale PostService.
+ */
+interface PostServiceInterface
+{
+    /**
+     * Retourne tous les articles publiés, avec un filtre optionnel par catégorie.
+     *
+     * @param int|null $categoryId Filtre optionnel par identifiant de catégorie
+     *
+     * @return Post[]
+     */
+    public function getAllPosts(?int $categoryId = null): array;
+
+    /**
+     * Retourne les articles les plus récents.
+     *
+     * @param int $limit Nombre maximum d'articles à retourner (défaut : 20)
+     *
+     * @return Post[]
+     */
+    public function getRecentPosts(int $limit = 20): array;
+
+    /**
+     * Retourne les articles d'un auteur donné.
+     *
+     * @param int      $userId     Identifiant de l'auteur
+     * @param int|null $categoryId Filtre optionnel par identifiant de catégorie
+     *
+     * @return Post[]
+     */
+    public function getPostsByUserId(int $userId, ?int $categoryId = null): array;
+
+    /**
+     * Retourne un article par son slug URL.
+     *
+     * @param string $slug Le slug URL de l'article
+     *
+     * @return Post L'article avec contenu sûr
+     *
+     * @throws NotFoundException Si aucun article ne correspond au slug
+     */
+    public function getPostBySlug(string $slug): Post;
+
+    /**
+     * Retourne un article par son identifiant.
+     *
+     * @param int $id Identifiant de l'article
+     *
+     * @return Post L'article avec son contenu
+     *
+     * @throws NotFoundException Si aucun article ne correspond à cet identifiant
+     */
+    public function getPostById(int $id): Post;
+
+    /**
+     * Crée un nouvel article.
+     *
+     * @param string   $title      Titre de l'article
+     * @param string   $content    Contenu HTML brut (sera sanitisé)
+     * @param int      $authorId   Identifiant de l'auteur
+     * @param int|null $categoryId Identifiant de la catégorie (null si sans catégorie)
+     *
+     * @return int L'identifiant de l'article créé
+     *
+     * @throws \InvalidArgumentException Si le titre ou le contenu sont invalides
+     */
+    public function createPost(string $title, string $content, int $authorId, ?int $categoryId = null): int;
+
+    /**
+     * Met à jour un article existant.
+     *
+     * @param int      $id           Identifiant de l'article à modifier
+     * @param string   $title        Nouveau titre
+     * @param string   $content      Nouveau contenu HTML brut (sera sanitisé)
+     * @param string   $newSlugInput Nouveau slug souhaité (vide = conserver l'actuel)
+     * @param int|null $categoryId   Identifiant de la catégorie (null si sans catégorie)
+     *
+     * @throws NotFoundException         Si l'article n'existe plus
+     * @throws \InvalidArgumentException Si le titre ou le contenu sont invalides
+     */
+    public function updatePost(
+        int $id,
+        string $title,
+        string $content,
+        string $newSlugInput = '',
+        ?int $categoryId = null,
+    ): void;
+
+    /**
+     * Recherche des articles par mots-clés dans le titre, le contenu et l'auteur.
+     *
+     * @param string   $query      La saisie utilisateur brute
+     * @param int|null $categoryId Filtre optionnel par identifiant de catégorie
+     * @param int|null $authorId   Filtre optionnel par identifiant d'auteur
+     *
+     * @return Post[]
+     */
+    public function searchPosts(string $query, ?int $categoryId = null, ?int $authorId = null): array;
+
+    /**
+     * Supprime un article.
+     *
+     * @param int $id Identifiant de l'article à supprimer
+     *
+     * @throws NotFoundException Si l'article n'existe plus au moment de la suppression
+     */
+    public function deletePost(int $id): void;
+}