Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Comments\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Comments\Domain\Model\Comment;
12use App\Modules\Comments\Domain\Model\CommentAttachment;
13use App\Modules\Comments\Domain\Model\CommentFilterScope;
14
15/**
16 * Repository interface for comment persistence and stream resolution.
17 *
18 * @package App\Modules\Comments\Domain\Repository
19 */
20interface CommentRepositoryInterface
21{
22    /**
23     * Finds stream of comments related to target record and its hierarchy rollup.
24     *
25     * @param string             $module        Target module machine name.
26     * @param int                $recordId      Target record ID.
27     * @param CommentFilterScope $scope         Active filter scope.
28     * @param int|null           $currentUserId Current logged user ID for 'mine' scope.
29     * @param int                $limit         Limit of comments to retrieve.
30     * @param int                $offset        Offset for pagination.
31     * @return array<int, Comment> List of comments ordered chronologically.
32     */
33    public function findStream(
34        string $module,
35        int $recordId,
36        CommentFilterScope $scope,
37        ?int $currentUserId,
38        int $limit = 100,
39        int $offset = 0
40    ): array;
41
42    /**
43     * Counts comments matching scope and hierarchy rollup.
44     *
45     * @param string             $module        Target module name.
46     * @param int                $recordId      Target record ID.
47     * @param CommentFilterScope $scope         Active filter scope.
48     * @param int|null           $currentUserId Current logged user ID.
49     * @return int Total matching comments count.
50     */
51    public function countStream(
52        string $module,
53        int $recordId,
54        CommentFilterScope $scope,
55        ?int $currentUserId
56    ): int;
57
58    /**
59     * Obtains aggregate counts for all filter tabs [all, mine, pinned, verified].
60     *
61     * @param string   $module        Target module name.
62     * @param int      $recordId      Target record ID.
63     * @param int|null $currentUserId Current logged user ID.
64     * @return array{all: int, mine: int, pinned: int, verified: int}
65     */
66    public function getStreamCounts(
67        string $module,
68        int $recordId,
69        ?int $currentUserId
70    ): array;
71
72    /**
73     * Finds a single comment by ID with loaded attachments and parent.
74     *
75     * @param int $commentId Comment primary key.
76     * @return Comment|null Comment entity or null.
77     */
78    public function findById(int $commentId): ?Comment;
79
80    /**
81     * Persists a new comment into database and returns its new ID.
82     *
83     * @param Comment $comment Comment entity to insert.
84     * @return int Inserted comment primary key ID.
85     */
86    public function save(Comment $comment): int;
87
88    /**
89     * Toggles pinned highlight state for a comment.
90     *
91     * @param int $commentId Comment ID.
92     * @return bool New pinned state (true=pinned, false=unpinned).
93     */
94    public function togglePin(int $commentId): bool;
95
96    /**
97     * Toggles verified state for a comment.
98     *
99     * @param int $commentId Comment ID.
100     * @return bool New verified state (true=verified, false=unverified).
101     */
102    public function toggleVerify(int $commentId): bool;
103
104    /**
105     * Marks a comment as deleted (record_status = 3 or hard delete).
106     *
107     * @param int $commentId Comment ID.
108     * @return bool True if record was updated.
109     */
110    public function delete(int $commentId): bool;
111
112    /**
113     * Persists an uploaded comment attachment record.
114     *
115     * @param CommentAttachment $attachment Attachment entity.
116     * @return int New attachment ID.
117     */
118    public function saveAttachment(CommentAttachment $attachment): int;
119
120    /**
121     * Finds comment attachment by primary key ID.
122     *
123     * @param int $attachmentId Attachment ID.
124     * @return CommentAttachment|null Found attachment or null.
125     */
126    public function findAttachmentById(int $attachmentId): ?CommentAttachment;
127
128    /**
129     * Finds comment attachment by secure public token.
130     *
131     * @param string $token Secure random token.
132     * @return CommentAttachment|null Found attachment or null.
133     */
134    public function findAttachmentByToken(string $token): ?CommentAttachment;
135
136    /**
137     * Removes an attachment record.
138     *
139     * @param int $attachmentId Attachment ID.
140     * @return bool True on success.
141     */
142    public function deleteAttachment(int $attachmentId): bool;
143}