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\Mail\Domain\Contract;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Mail\Domain\Model\MailMessageDetailDto;
12use App\Modules\Mail\Domain\Model\MailMessageSummaryDto;
13use App\Modules\Mail\Domain\Model\MailMimePartDto;
14use App\Modules\Mail\Domain\Model\MailSearchCriteriaDto;
15
16/**
17 * Webmail Message Service Contract.
18 *
19 * Coordinates message listing, server-side filtering, isolated HTML sanitization,
20 * flag toggling, and multi-message batch operations.
21 *
22 * @package App\Modules\Mail\Domain\Contract
23 */
24interface WebmailMessageServiceInterface
25{
26    /**
27     * Fetches paginated message list for a specific mailbox folder.
28     *
29     * @param int                   $mailboxId Mailbox primary key.
30     * @param int                   $userId    Current user ID.
31     * @param MailSearchCriteriaDto $criteria  Search and sort parameters.
32     * @param int                   $page      Page index (1-based).
33     * @param int                   $perPage   Items per page.
34     * @return array{messages: array<MailMessageSummaryDto>, total: int}
35     */
36    public function fetchMessages(
37        int $mailboxId,
38        int $userId,
39        MailSearchCriteriaDto $criteria,
40        int $page = 1,
41        int $perPage = 25
42    ): array;
43
44    /**
45     * Retrieves sanitized message details.
46     *
47     * @param int    $mailboxId         Mailbox primary key.
48     * @param int    $userId            Current user ID.
49     * @param string $folder            IMAP folder name.
50     * @param string $messageUid        Message UID string.
51     * @param bool   $markAsSeen        Whether to flag message as seen.
52     * @param bool   $allowRemoteImages Whether to allow remote external images.
53     * @return MailMessageDetailDto Sanitized message detail.
54     */
55    public function getMessageDetail(
56        int $mailboxId,
57        int $userId,
58        string $folder,
59        string $messageUid,
60        bool $markAsSeen = true,
61        bool $allowRemoteImages = false
62    ): MailMessageDetailDto;
63
64    /**
65     * Streams binary payload of a single MIME attachment part.
66     */
67    public function getMimePart(
68        int $mailboxId,
69        int $userId,
70        string $folder,
71        string $messageUid,
72        string $partId
73    ): MailMimePartDto;
74
75    /**
76     * Retrieves full raw RFC 822 / EML message source string.
77     */
78    public function getRawMessageSource(
79        int $mailboxId,
80        int $userId,
81        string $folder,
82        string $messageUid
83    ): string;
84
85    /**
86     * Toggles flags (\Seen, \Flagged) for given messages.
87     *
88     * @param int           $mailboxId Mailbox primary key.
89     * @param int           $userId    Current user ID.
90     * @param string        $folder    Mailbox folder path.
91     * @param array<string> $uids      Target message UIDs.
92     * @param array<string> $flags     Flag names.
93     * @param bool          $add       True to set, false to unset.
94     */
95    public function setFlags(
96        int $mailboxId,
97        int $userId,
98        string $folder,
99        array $uids,
100        array $flags,
101        bool $add = true
102    ): void;
103
104    /**
105     * Toggles an RFC 5788 keyword/label on specified messages.
106     *
107     * @param int           $mailboxId Mailbox ID.
108     * @param int           $userId    User ID.
109     * @param string        $folder    Folder path.
110     * @param array<string> $uids      Message UIDs.
111     * @param string        $keyword   Keyword flag (e.g. $Important, $Work).
112     * @param bool          $add       True to add, false to remove.
113     */
114    public function toggleKeyword(
115        int $mailboxId,
116        int $userId,
117        string $folder,
118        array $uids,
119        string $keyword,
120        bool $add = true
121    ): void;
122
123    /**
124     * Moves messages from source folder to target folder.
125     *
126     * @param int           $mailboxId    Mailbox ID.
127     * @param int           $userId       User ID.
128     * @param string        $sourceFolder Source folder.
129     * @param string        $targetFolder Target folder.
130     * @param array<string> $uids         Message UIDs.
131     */
132    public function moveMessages(
133        int $mailboxId,
134        int $userId,
135        string $sourceFolder,
136        string $targetFolder,
137        array $uids
138    ): void;
139}