1 <?php
2 /* --------------------------------------------------------------
3 EmailServiceInterface.inc.php 2015-02-05 gm
4 Gambio GmbH
5 http://www.gambio.de
6 Copyright (c) 2015 Gambio GmbH
7 Released under the GNU General Public License (Version 2)
8 [http://www.gnu.org/licenses/gpl-2.0.html]
9 --------------------------------------------------------------
10 */
11
12 /**
13 * Interface EmailServiceInterface
14 *
15 * @category System
16 * @package Email
17 * @subpackage Interfaces
18 */
19 interface EmailServiceInterface
20 {
21 /**
22 * Creates a new email
23 *
24 * Use this method to can a valid email object that can be sent without any
25 * additional modification. Optionally you can add more information to the
26 * email object such as attachments, BCC & CC contacts etc.
27 *
28 * @param EmailContactInterface $sender Contains the sender information.
29 * @param EmailContactInterface $recipient Contains the recipient information.
30 * @param EmailSubjectInterface $subject Email record subject.
31 * @param EmailContentInterface $content (optional) Html content of the email.
32 *
33 * @return EmailInterface Valid email.
34 */
35 public function create(EmailContactInterface $sender,
36 EmailContactInterface $recipient,
37 EmailSubjectInterface $subject,
38 EmailContentInterface $content = null);
39
40
41 /**
42 * Sends and saves an email.
43 *
44 * @param EmailInterface $email Contains email information.
45 */
46 public function send(EmailInterface $email);
47
48
49 /**
50 * Saves an email as pending (will not be sent).
51 *
52 * @param EmailInterface $email Contains email information.
53 */
54 public function queue(EmailInterface $email);
55
56
57 /**
58 * Writes an email instance to the DB.
59 *
60 * This method will store an email entity just the way it is without modifying other properties
61 * like the "send" or "queue" methods do. If you use this method or the "writeCollection" make
62 * sure that all the email properties are the desired ones.
63 *
64 * @param EmailInterface $email Email to write.
65 */
66 public function write(EmailInterface $email);
67
68
69 /**
70 * Returns an email by id.
71 *
72 * @param IdType $id The database ID that matches the email record.
73 *
74 * @return EmailInterface Contains the email information.
75 */
76 public function getById(IdType $id);
77
78
79 /**
80 * Finds an email by ID.
81 *
82 * @param IdType $id The record ID that matches the email.
83 *
84 * @return EmailInterface|null Email or null if not found.
85 */
86 public function findById(IdType $id);
87
88
89 /**
90 * Removes an email from the database.
91 *
92 * @param EmailInterface $email Contains the email information.
93 */
94 public function delete(EmailInterface $email);
95
96
97 /**
98 * Filters email records with provided keyword string.
99 *
100 * @param string $p_keyword String to be used for filtering the email records.
101 * @param array $limit (optional) Array that contains LIMIT and OFFSET value
102 * e.g. array( 'limit' => 10, 'offset' => 5 )
103 * @param array $order (optional) Contains arrays with column, direction pairs
104 * e.g. array( 'column' => 'direction' )
105 *
106 * @return EmailCollection Email collection containing the email records.
107 */
108 public function filter($p_keyword, array $limit = array(), array $order = array());
109
110
111 /**
112 * Validate a string email address.
113 *
114 * @param string $p_emailAddress Email address to be validated.
115 *
116 * @return bool Returns the validation result (true for success, false for failure).
117 */
118 public function validateEmailAddress($p_emailAddress);
119
120
121 /**
122 * Sends pending email records.
123 */
124 public function sendPending();
125
126
127 /**
128 * Return pending email records as an email collection.
129 *
130 * @return EmailCollectionInterface The pending emails.
131 */
132 public function getPending();
133
134
135 /**
136 * Returns sent email records as an email collection.
137 *
138 * @return EmailCollectionInterface Sent email records.
139 */
140 public function getSent();
141
142
143 /**
144 * Returns all email records from the database.
145 *
146 * @return EmailCollection Email records.
147 */
148 public function getAll();
149
150
151 /**
152 * Sends a collection of emails.
153 *
154 * @param EmailCollectionInterface $collection Email collection to send.
155 */
156 public function sendCollection(EmailCollectionInterface $collection);
157
158
159 /**
160 * Queues a collection of emails.
161 *
162 * @param EmailCollectionInterface $collection Email collection to queue.
163 */
164 public function queueCollection(EmailCollectionInterface $collection);
165
166
167 /**
168 * Writes a collection of emails into database.
169 *
170 * @param EmailCollectionInterface $collection Email collection to write.
171 */
172 public function writeCollection(EmailCollectionInterface $collection);
173
174
175 /**
176 * Deletes a collection of emails.
177 *
178 * @param EmailCollectionInterface $collection Email collection to delete.
179 */
180 public function deleteCollection(EmailCollectionInterface $collection);
181
182
183 /**
184 * Returns the current count of the email records in the database.
185 *
186 * @param string $p_filterKeyword (optional) If provided the records will be filtered.
187 *
188 * @return int The row number of the email table.
189 */
190 public function getRecordCount($p_filterKeyword = '');
191 }