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\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Mail\Domain\Model\ClientMailbox;
12use App\Modules\Mail\Domain\Model\MailQueueItem;
13use App\Modules\Mail\Domain\Model\MailServer;
14use App\Modules\Mail\Domain\Model\MailSmtp;
15use App\Modules\Mail\Domain\Model\MailTemplate;
16
17/**
18 * Mail Repository Contract Interface.
19 *
20 * @package App\Modules\Mail\Domain\Repository
21 */
22interface MailRepositoryInterface
23{
24    /**
25     * Finds mail server configuration by ID.
26     *
27     * @param int $id Mail server ID.
28     * @return MailServer|null Mail server instance or null.
29     */
30    public function findMailServerById(int $id): ?MailServer;
31
32    /**
33     * Finds default active mail server.
34     *
35     * @return MailServer|null Default server or first active.
36     */
37    public function findDefaultMailServer(): ?MailServer;
38
39    /**
40     * Finds all active mail servers accessible to clients.
41     *
42     * @return array<int, MailServer> List of active servers.
43     */
44    public function findAllActiveServers(): array;
45
46    /**
47     * Finds client mailbox by ID.
48     *
49     * @param int $id Client mailbox ID.
50     * @return ClientMailbox|null Mailbox instance or null.
51     */
52    public function findClientMailboxById(int $id): ?ClientMailbox;
53
54    /**
55     * Finds active SMTP configuration by ID.
56     *
57     * @param int $id SMTP record ID.
58     * @return MailSmtp|null SMTP model instance or null.
59     */
60    public function findSmtpById(int $id): ?MailSmtp;
61
62    /**
63     * Finds default active SMTP server.
64     *
65     * @return MailSmtp|null Default SMTP server or first active.
66     */
67    public function findDefaultSmtp(): ?MailSmtp;
68
69    /**
70     * Finds template by unique code and language.
71     *
72     * @param string $code Template machine code.
73     * @param string $languageCode Preferred language code.
74     * @return MailTemplate|null Template model instance or null.
75     */
76    public function findTemplateByCode(string $code, string $languageCode = 'en'): ?MailTemplate;
77
78    /**
79     * Enqueues an outgoing email message.
80     *
81     * @param MailQueueItem $item Queue item model.
82     * @return int Inserted queue record ID.
83     */
84    public function enqueue(MailQueueItem $item): int;
85
86    /**
87     * Fetches pending email queue items eligible for sending.
88     *
89     * @param int $limit Maximum records to fetch.
90     * @return array<int, MailQueueItem> Array of pending queue items.
91     */
92    public function findPendingQueueItems(int $limit = 20): array;
93
94    /**
95     * Updates queue item status to processing.
96     *
97     * @param int $id Queue item ID.
98     * @return bool True on success.
99     */
100    public function markAsProcessing(int $id): bool;
101
102    /**
103     * Updates queue item status to sent.
104     *
105     * @param int $id Queue item ID.
106     * @return bool True on success.
107     */
108    public function markAsSent(int $id): bool;
109
110    /**
111     * Updates queue item status to failed with error message.
112     *
113     * @param int    $id    Queue item ID.
114     * @param string $error Error message description.
115     * @return bool True on success.
116     */
117    public function markAsFailed(int $id, string $error): bool;
118
119    /**
120     * Resets zombie queue items stuck in processing status back to failed.
121     *
122     * @param int $timeoutSeconds Timeout threshold in seconds (default 300s = 5 min).
123     * @return int Number of recovered zombie items.
124     */
125    public function resetStuckToFailed(int $timeoutSeconds = 300): int;
126
127    /**
128     * Records an outbound email message in emails table.
129     *
130     * @param array<string, mixed> $data Outbound email attributes.
131     * @return int Inserted email record ID.
132     */
133    public function recordOutboundEmail(array $data): int;
134}
135