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\ClientMailbox;
12use App\Modules\Mail\Domain\Model\MailFolderDto;
13use App\Modules\Mail\Domain\Model\MailFolderStatusDto;
14use App\Modules\Mail\Domain\Model\MailMessageDetailDto;
15use App\Modules\Mail\Domain\Model\MailMessageSummaryDto;
16use App\Modules\Mail\Domain\Model\MailMimePartDto;
17use App\Modules\Mail\Domain\Model\MailOutgoingMessageDto;
18use App\Modules\Mail\Domain\Model\MailSearchCriteriaDto;
19use App\Modules\Mail\Domain\Model\MailSendResultDto;
20use App\Modules\Mail\Domain\Model\MailServer;
21
22/**
23 * Universal Mail Protocol Driver Contract.
24 *
25 * Implements decoupled mail protocol operations (IMAP, JMAP, Exchange/Graph)
26 * isolating presentation and business layers from vendor/protocol implementations.
27 *
28 * @package App\Modules\Mail\Domain\Contract
29 */
30interface MailProtocolDriverInterface
31{
32    /**
33     * Connects to mail server and authenticates credentials.
34     *
35     * @param ClientMailbox   $mailbox Mailbox account definition.
36     * @param MailServer|null $server  Mail server infrastructure node.
37     */
38    public function connect(ClientMailbox $mailbox, ?MailServer $server = null): void;
39
40    /**
41     * Pings connection to verify session liveness.
42     *
43     * @return bool True if active.
44     */
45    public function ping(): bool;
46
47    /**
48     * Closes protocol connection.
49     */
50    public function disconnect(): void;
51
52    /**
53     * Lists mailbox folders with hierarchical children and special-use attributes.
54     *
55     * @return array<MailFolderDto> Root folder list.
56     */
57    public function listFolders(): array;
58
59    /**
60     * Queries folder status counters (total, unseen, UIDNEXT, HIGHESTMODSEQ).
61     *
62     * @param string $folderPath Protocol folder path.
63     * @return MailFolderStatusDto Folder status.
64     */
65    public function getFolderStatus(string $folderPath): MailFolderStatusDto;
66
67    /**
68     * Creates new mailbox folder.
69     *
70     * @param string      $folderName   Folder name.
71     * @param string|null $parentFolder Optional parent folder path.
72     * @return MailFolderDto Created folder DTO.
73     */
74    public function createFolder(string $folderName, ?string $parentFolder = null): MailFolderDto;
75
76    /**
77     * Renames or moves existing folder.
78     *
79     * @param string $oldPath Source folder path.
80     * @param string $newPath Target folder path.
81     */
82    public function renameFolder(string $oldPath, string $newPath): void;
83
84    /**
85     * Deletes mailbox folder.
86     *
87     * @param string $folderPath Folder path.
88     */
89    public function deleteFolder(string $folderPath): void;
90
91    /**
92     * Fetches paginated message summaries matching filter criteria.
93     *
94     * @param string                $folderPath Mailbox folder path.
95     * @param MailSearchCriteriaDto $criteria   Filter and sort criteria.
96     * @param int                   $page       1-based page number.
97     * @param int                   $perPage    Number of items per page.
98     * @return array{messages: array<MailMessageSummaryDto>, total: int} Paginated result.
99     */
100    public function fetchMessages(
101        string $folderPath,
102        MailSearchCriteriaDto $criteria,
103        int $page,
104        int $perPage
105    ): array;
106
107    /**
108     * Fetches complete message payload (body, attachments, auth headers).
109     *
110     * @param string $folderPath Mailbox folder path.
111     * @param string $messageUid Message UID.
112     * @param bool   $markAsSeen Whether to mark message as seen.
113     * @return MailMessageDetailDto Populated message detail.
114     */
115    public function getMessageDetail(
116        string $folderPath,
117        string $messageUid,
118        bool $markAsSeen = true
119    ): MailMessageDetailDto;
120
121    /**
122     * Streams raw binary payload of a single MIME part (attachment or inline asset).
123     *
124     * @param string $folderPath Mailbox folder path.
125     * @param string $messageUid Message UID.
126     * @param string $partId     MIME part ID.
127     * @return MailMimePartDto Populated MIME part DTO.
128     */
129    public function getMimePartStream(string $folderPath, string $messageUid, string $partId): MailMimePartDto;
130
131    /**
132     * Retrieves full raw RFC 822 / EML message source string.
133     *
134     * @param string $folderPath Mailbox folder path.
135     * @param string $messageUid Message UID.
136     * @return string Raw EML source.
137     */
138    public function getRawMessageSource(string $folderPath, string $messageUid): string;
139
140    /**
141     * Updates message flags (\Seen, \Flagged, \Answered, \Deleted).
142     *
143     * @param string        $folderPath  Mailbox folder path.
144     * @param array<string> $messageUids Target message UIDs.
145     * @param array<string> $flags       Flag strings.
146     * @param bool          $add         True to add flags, false to remove.
147     */
148    public function setFlags(string $folderPath, array $messageUids, array $flags, bool $add = true): void;
149
150    /**
151     * Moves messages from source folder to target folder.
152     *
153     * @param string        $sourceFolder Source folder path.
154     * @param string        $targetFolder Target folder path.
155     * @param array<string> $messageUids  Message UIDs to move.
156     */
157    public function moveMessages(string $sourceFolder, string $targetFolder, array $messageUids): void;
158
159    /**
160     * Copies messages from source folder to target folder.
161     *
162     * @param string        $sourceFolder Source folder path.
163     * @param string        $targetFolder Target folder path.
164     * @param array<string> $messageUids  Message UIDs to copy.
165     */
166    public function copyMessages(string $sourceFolder, string $targetFolder, array $messageUids): void;
167
168    /**
169     * Deletes messages from folder.
170     *
171     * @param string        $folderPath  Mailbox folder path.
172     * @param array<string> $messageUids Target message UIDs.
173     * @param bool          $expunge     Whether to permanently expunge immediately.
174     */
175    public function deleteMessages(string $folderPath, array $messageUids, bool $expunge = true): void;
176
177    /**
178     * Stores or updates message draft in Drafts folder.
179     *
180     * @param MailOutgoingMessageDto $message          Outgoing message payload.
181     * @param string|null            $existingDraftUid Optional UID of draft to replace.
182     * @return string Stored draft message UID.
183     */
184    public function saveDraft(MailOutgoingMessageDto $message, ?string $existingDraftUid = null): string;
185
186    /**
187     * Sends message via dedicated mailbox transport and appends copy to Sent folder.
188     *
189     * @param MailOutgoingMessageDto $message Outgoing message payload.
190     * @return MailSendResultDto Send outcome.
191     */
192    public function sendMessage(MailOutgoingMessageDto $message): MailSendResultDto;
193
194    /**
195     * Retrieves mailbox storage quota and usage if supported by the protocol.
196     *
197     * @return array{used_kb: int, total_kb: int, percent: float}|null Quota statistics or null if unsupported.
198     */
199    public function getQuota(): ?array;
200
201    /**
202     * Appends a raw RFC822/MIME message payload to the specified folder with given flags.
203     *
204     * @param string        $folderPath Target folder path.
205     * @param string        $rawPayload Raw RFC822 message payload.
206     * @param array<string> $flags      IMAP flags (e.g., '\Seen', '\Flagged').
207     * @return string|null Generated or assigned UID if available.
208     */
209    public function appendRawMessage(string $folderPath, string $rawPayload, array $flags = []): ?string;
210}
211
212
213