feat(api): added pagination, sorting, and filtering for API controllers (#3830)

Author: thorsten

CHANGELOG.md

@@ -12,6 +12,7 @@ This is a log of major user-visible changes in each phpMyFAQ release.
 - added Symfony Router for frontend (Thorsten)
 - added API for glossary definitions (Thorsten)
 - added admin log CSV export feature (Thorsten)
+- added pagination, sorting, and filtering for APIs (Thorsten)
 - improved audit and activity log with comprehensive security event tracking (Thorsten)
 - improved API errors with formatted RFC 7807 Problem Details JSON responses (Thorsten)
 - migrated codebase to use PHP 8.4 language features (Thorsten)

phpmyfaq/src/phpMyFAQ/Comment/CommentsRepository.php

@@ -43,22 +43,110 @@ public function fetchByReferenceIdAndType(int $referenceId, string $type): array
                 %sfaqcomments
             WHERE
                 type = '%s'
-            AND 
+            AND
+                id = %d
+        SQL;
+
+        $query = sprintf(
+            $sql,
+            Database::getTablePrefix(),
+            $this->coreConfiguration->getDb()->escape($type),
+            $referenceId,
+        );
+
+        $result = $this->coreConfiguration->getDb()->query($query);
+        $rows = $this->coreConfiguration->getDb()->fetchAll($result);
+        return is_array($rows) ? $rows : [];
+    }
+
+    /**
+     * Fetch comments with pagination and sorting
+     *
+     * @param int $referenceId Record ID
+     * @param string $type Type (faq or news)
+     * @param int $limit Items per page
+     * @param int $offset Offset for pagination
+     * @param string $sortField Field to sort by
+     * @param string $sortOrder Sort order (ASC or DESC)
+     * @return array<int, object>
+     */
+    public function fetchPaginated(
+        int $referenceId,
+        string $type,
+        int $limit,
+        int $offset,
+        string $sortField = 'id_comment',
+        string $sortOrder = 'ASC',
+    ): array {
+        $allowedSortFields = ['id_comment', 'id', 'usr', 'email', 'datum'];
+        $sortField = in_array($sortField, $allowedSortFields) ? $sortField : 'id_comment';
+        $sortOrder = strtoupper($sortOrder) === 'DESC' ? 'DESC' : 'ASC';
+
+        $sql = <<<SQL
+            SELECT
+                id_comment, id, usr, email, comment, datum
+            FROM
+                %sfaqcomments
+            WHERE
+                type = '%s'
+            AND
                 id = %d
+            ORDER BY
+                %s %s
+            LIMIT %d OFFSET %d
         SQL;
 
         $query = sprintf(
             $sql,
             Database::getTablePrefix(),
             $this->coreConfiguration->getDb()->escape($type),
             $referenceId,
+            $sortField,
+            $sortOrder,
+            $limit,
+            $offset,
         );
 
         $result = $this->coreConfiguration->getDb()->query($query);
         $rows = $this->coreConfiguration->getDb()->fetchAll($result);
         return is_array($rows) ? $rows : [];
     }
 
+    /**
+     * Count total comments for a reference ID and type
+     *
+     * @param int $referenceId Record ID
+     * @param string $type Type (faq or news)
+     * @return int
+     */
+    public function countByReferenceIdAndType(int $referenceId, string $type): int
+    {
+        $sql = <<<SQL
+            SELECT
+                COUNT(*) AS total
+            FROM
+                %sfaqcomments
+            WHERE
+                type = '%s'
+            AND
+                id = %d
+        SQL;
+
+        $query = sprintf(
+            $sql,
+            Database::getTablePrefix(),
+            $this->coreConfiguration->getDb()->escape($type),
+            $referenceId,
+        );
+
+        $result = $this->coreConfiguration->getDb()->query($query);
+        if ($row = $this->coreConfiguration->getDb()->fetchObject($result)) {
+            return (int) $row->total;
+        }
+
+        return 0;
+    }
+
     public function insert(Comment $comment): bool
     {
         $helpedValue = $comment->hasHelped();

phpmyfaq/src/phpMyFAQ/Comments.php

@@ -69,6 +69,58 @@ public function getCommentsData(int $referenceId, string $type): array
         return $comments;
     }
 
+    /**
+     * Returns paginated user comments from a record by type.
+     *
+     * @param int $referenceId Record ID
+     * @param string $type Record type: {faq|news}
+     * @param int $limit Items per page
+     * @param int $offset Offset for pagination
+     * @param string $sortField Field to sort by
+     * @param string $sortOrder Sort order (ASC or DESC)
+     *
+     * @return Comment[]
+     */
+    public function getCommentsDataPaginated(
+        int $referenceId,
+        string $type,
+        int $limit,
+        int $offset,
+        string $sortField = 'id_comment',
+        string $sortOrder = 'ASC',
+    ): array {
+        $comments = [];
+
+        $rows = $this->commentsRepository->fetchPaginated($referenceId, $type, $limit, $offset, $sortField, $sortOrder);
+
+        foreach ($rows as $row) {
+            $comment = new Comment();
+            $comment
+                ->setId((int) $row->id_comment)
+                ->setRecordId((int) $row->id)
+                ->setComment($row->comment)
+                ->setDate(Date::createIsoDateFromUnixTimestamp($row->datum, DateTimeInterface::ATOM))
+                ->setUsername($row->usr)
+                ->setEmail($row->email)
+                ->setType($type);
+            $comments[] = $comment;
+        }
+
+        return $comments;
+    }
+
+    /**
+     * Count total comments for a reference ID and type.
+     *
+     * @param int $referenceId Record ID
+     * @param string $type Record type: {faq|news}
+     * @return int
+     */
+    public function countComments(int $referenceId, string $type): int
+    {
+        return $this->commentsRepository->countByReferenceIdAndType($referenceId, $type);
+    }
+
     /**
      * Adds a new comment.
      */

phpmyfaq/src/phpMyFAQ/Controller/Api/CommentController.php

@@ -22,31 +22,21 @@
 use Exception;
 use OpenApi\Attributes as OA;
 use phpMyFAQ\Comments;
-use phpMyFAQ\Controller\AbstractController;
 use phpMyFAQ\Entity\CommentType;
 use phpMyFAQ\Filter;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
-use Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException;
 
-final class CommentController extends AbstractController
+final class CommentController extends AbstractApiController
 {
-    public function __construct()
-    {
-        parent::__construct();
-
-        if (!$this->isApiEnabled()) {
-            throw new UnauthorizedHttpException(challenge: 'API is not enabled');
-        }
-    }
-
     /**
      * @throws Exception
-     */ #[OA\Get(
+     */
+    #[OA\Get(
         path: '/api/v3.2/comments/{faqId}',
         operationId: 'getComments',
-        description: 'Returns a list of comments for a given FAQ record ID.',
+        description: 'Returns a paginated list of comments for a given FAQ record ID.',
         tags: ['Public Endpoints'],
     )]
     #[OA\Header(
@@ -61,34 +51,116 @@ public function __construct()
         required: true,
         schema: new OA\Schema(type: 'integer'),
     )]
-    #[OA\Response(response: 200, description: 'If the FAQ has at least one comment.', content: new OA\JsonContent(
-        example: '
-        [
-            {
-                "id": 2,
-                "recordId": 142,
-                "categoryId": null,
-                "type": "faq",
-                "username": "phpMyFAQ User",
-                "email": "[email protected]",
-                "comment": "Foo! Bar?",
-                "date": "2019-12-24T12:24:57+0100",
-                "helped": null
+    #[OA\Parameter(
+        name: 'page',
+        description: 'Page number for pagination (page-based)',
+        in: 'query',
+        required: false,
+        schema: new OA\Schema(type: 'integer', default: 1),
+    )]
+    #[OA\Parameter(
+        name: 'per_page',
+        description: 'Items per page (page-based, max 100)',
+        in: 'query',
+        required: false,
+        schema: new OA\Schema(type: 'integer', default: 25),
+    )]
+    #[OA\Parameter(
+        name: 'limit',
+        description: 'Number of items to return (offset-based, max 100)',
+        in: 'query',
+        required: false,
+        schema: new OA\Schema(type: 'integer', default: 25),
+    )]
+    #[OA\Parameter(
+        name: 'offset',
+        description: 'Starting offset (offset-based)',
+        in: 'query',
+        required: false,
+        schema: new OA\Schema(type: 'integer', default: 0),
+    )]
+    #[OA\Parameter(name: 'sort', description: 'Field to sort by', in: 'query', required: false, schema: new OA\Schema(
+        type: 'string',
+        default: 'id_comment',
+        enum: ['id_comment', 'id', 'usr', 'email', 'datum'],
+    ))]
+    #[OA\Parameter(
+        name: 'order',
+        description: 'Sort direction',
+        in: 'query',
+        required: false,
+        schema: new OA\Schema(type: 'string', default: 'asc', enum: ['asc', 'desc']),
+    )]
+    #[OA\Response(response: 200, description: 'Returns paginated comments for the FAQ.', content: new OA\JsonContent(
+        example: '{
+            "success": true,
+            "data": [
+                {
+                    "id": 2,
+                    "recordId": 142,
+                    "categoryId": null,
+                    "type": "faq",
+                    "username": "phpMyFAQ User",
+                    "email": "[email protected]",
+                    "comment": "Foo! Bar?",
+                    "date": "2019-12-24T12:24:57+0100",
+                    "helped": null
+                }
+            ],
+            "meta": {
+                "pagination": {
+                    "total": 50,
+                    "count": 25,
+                    "per_page": 25,
+                    "current_page": 1,
+                    "total_pages": 2,
+                    "links": {
+                        "first": "/api/v3.2/comments/142?page=1&per_page=25",
+                        "last": "/api/v3.2/comments/142?page=2&per_page=25",
+                        "prev": null,
+                        "next": "/api/v3.2/comments/142?page=2&per_page=25"
+                    }
+                },
+                "sorting": {
+                    "field": "id_comment",
+                    "order": "asc"
+                }
             }
-        ]',
+        }',
     ))]
-    #[OA\Response(response: 404, description: 'If the FAQ has no comments.', content: new OA\JsonContent(example: []))]
+    #[OA\Response(
+        response: 200,
+        description: 'If no comments are found, returns empty data array.',
+        content: new OA\JsonContent(example: '{"success": true, "data": []}'),
+    )]
     public function list(Request $request): JsonResponse
     {
         $recordId = (int) Filter::filterVar($request->attributes->get(key: 'recordId'), FILTER_VALIDATE_INT);
 
         /** @var Comments $comments */
         $comments = $this->container->get(id: 'phpmyfaq.comments');
-        $result = $comments->getCommentsData($recordId, CommentType::FAQ);
-        if ((is_countable($result) ? count($result) : 0) === 0) {
-            $this->json($result, Response::HTTP_NOT_FOUND);
-        }
 
-        return $this->json($result, Response::HTTP_OK);
+        // Get pagination and sorting parameters
+        $pagination = $this->getPaginationRequest();
+        $sort = $this->getSortRequest(
+            allowedFields: ['id_comment', 'id', 'usr', 'email', 'datum'],
+            defaultField: 'id_comment',
+            defaultOrder: 'asc',
+        );
+
+        // Get paginated comments
+        $result = $comments->getCommentsDataPaginated(
+            referenceId: $recordId,
+            type: CommentType::FAQ,
+            limit: $pagination->limit,
+            offset: $pagination->offset,
+            sortField: $sort->getField() ?? 'id_comment',
+            sortOrder: $sort->getOrderSql(),
+        );
+
+        // Get total count
+        $total = $comments->countComments($recordId, CommentType::FAQ);
+
+        return $this->paginatedResponse(data: $result, total: $total, pagination: $pagination, sort: $sort);
     }
 }