Added feature #15998: Create a new API to send mails based on SwiftMailer to replace...
[Packages/TYPO3.CMS.git] / typo3 / contrib / swiftmailer / classes / Swift / Mime / Headers / MailboxHeader.php
1 <?php
2
3 /*
4 * This file is part of SwiftMailer.
5 * (c) 2004-2009 Chris Corbyn
6 *
7 * For the full copyright and license information, please view the LICENSE
8 * file that was distributed with this source code.
9 */
10
11 //@require 'Swift/Mime/Headers/AbstractHeader.php';
12 //@require 'Swift/Mime/HeaderEncoder.php';
13
14 /**
15 * A Mailbox Address MIME Header for something like From or Sender.
16 * @package Swift
17 * @subpackage Mime
18 * @author Chris Corbyn
19 */
20 class Swift_Mime_Headers_MailboxHeader extends Swift_Mime_Headers_AbstractHeader
21 {
22
23 /**
24 * The mailboxes used in this Header.
25 * @var string[]
26 * @access private
27 */
28 private $_mailboxes = array();
29
30 /**
31 * Creates a new MailboxHeader with $name.
32 * @param string $name of Header
33 * @param Swift_Mime_HeaderEncoder $encoder
34 */
35 public function __construct($name, Swift_Mime_HeaderEncoder $encoder)
36 {
37 $this->setFieldName($name);
38 $this->setEncoder($encoder);
39 $this->initializeGrammar();
40 }
41
42 /**
43 * Get the type of Header that this instance represents.
44 * @return int
45 * @see TYPE_TEXT, TYPE_PARAMETERIZED, TYPE_MAILBOX
46 * @see TYPE_DATE, TYPE_ID, TYPE_PATH
47 */
48 public function getFieldType()
49 {
50 return self::TYPE_MAILBOX;
51 }
52
53 /**
54 * Set the model for the field body.
55 * This method takes a string, or an array of addresses.
56 * @param mixed $model
57 * @throws Swift_RfcComplianceException
58 */
59 public function setFieldBodyModel($model)
60 {
61 $this->setNameAddresses($model);
62 }
63
64 /**
65 * Get the model for the field body.
66 * This method returns an associative array like {@link getNameAddresses()}
67 * @return array
68 * @throws Swift_RfcComplianceException
69 */
70 public function getFieldBodyModel()
71 {
72 return $this->getNameAddresses();
73 }
74
75 /**
76 * Set a list of mailboxes to be shown in this Header.
77 * The mailboxes can be a simple array of addresses, or an array of
78 * key=>value pairs where (email => personalName).
79 * Example:
80 * <code>
81 * <?php
82 * //Sets two mailboxes in the Header, one with a personal name
83 * $header->setNameAddresses(array(
84 * 'chris@swiftmailer.org' => 'Chris Corbyn',
85 * 'mark@swiftmailer.org' //No associated personal name
86 * ));
87 * ?>
88 * </code>
89 * @param string|string[] $mailboxes
90 * @throws Swift_RfcComplianceException
91 * @see __construct()
92 * @see setAddresses()
93 * @see setValue()
94 */
95 public function setNameAddresses($mailboxes)
96 {
97 $this->_mailboxes = $this->normalizeMailboxes((array) $mailboxes);
98 $this->setCachedValue(null); //Clear any cached value
99 }
100
101 /**
102 * Get the full mailbox list of this Header as an array of valid RFC 2822 strings.
103 * Example:
104 * <code>
105 * <?php
106 * $header = new Swift_Mime_Headers_MailboxHeader('From',
107 * array('chris@swiftmailer.org' => 'Chris Corbyn',
108 * 'mark@swiftmailer.org' => 'Mark Corbyn')
109 * );
110 * print_r($header->getNameAddressStrings());
111 * // array (
112 * // 0 => Chris Corbyn <chris@swiftmailer.org>,
113 * // 1 => Mark Corbyn <mark@swiftmailer.org>
114 * // )
115 * ?>
116 * </code>
117 * @return string[]
118 * @throws Swift_RfcComplianceException
119 * @see getNameAddresses()
120 * @see toString()
121 */
122 public function getNameAddressStrings()
123 {
124 return $this->_createNameAddressStrings($this->getNameAddresses());
125 }
126
127 /**
128 * Get all mailboxes in this Header as key=>value pairs.
129 * The key is the address and the value is the name (or null if none set).
130 * Example:
131 * <code>
132 * <?php
133 * $header = new Swift_Mime_Headers_MailboxHeader('From',
134 * array('chris@swiftmailer.org' => 'Chris Corbyn',
135 * 'mark@swiftmailer.org' => 'Mark Corbyn')
136 * );
137 * print_r($header->getNameAddresses());
138 * // array (
139 * // chris@swiftmailer.org => Chris Corbyn,
140 * // mark@swiftmailer.org => Mark Corbyn
141 * // )
142 * ?>
143 * </code>
144 * @return string[]
145 * @see getAddresses()
146 * @see getNameAddressStrings()
147 */
148 public function getNameAddresses()
149 {
150 return $this->_mailboxes;
151 }
152
153 /**
154 * Makes this Header represent a list of plain email addresses with no names.
155 * Example:
156 * <code>
157 * <?php
158 * //Sets three email addresses as the Header data
159 * $header->setAddresses(
160 * array('one@domain.tld', 'two@domain.tld', 'three@domain.tld')
161 * );
162 * ?>
163 * </code>
164 * @param string[] $addresses
165 * @throws Swift_RfcComplianceException
166 * @see setNameAddresses()
167 * @see setValue()
168 */
169 public function setAddresses($addresses)
170 {
171 return $this->setNameAddresses(array_values((array) $addresses));
172 }
173
174 /**
175 * Get all email addresses in this Header.
176 * @return string[]
177 * @see getNameAddresses()
178 */
179 public function getAddresses()
180 {
181 return array_keys($this->_mailboxes);
182 }
183
184 /**
185 * Remove one or more addresses from this Header.
186 * @param string|string[] $addresses
187 */
188 public function removeAddresses($addresses)
189 {
190 $this->setCachedValue(null);
191 foreach ((array) $addresses as $address)
192 {
193 unset($this->_mailboxes[$address]);
194 }
195 }
196
197 /**
198 * Get the string value of the body in this Header.
199 * This is not necessarily RFC 2822 compliant since folding white space will
200 * not be added at this stage (see {@link toString()} for that).
201 * @return string
202 * @throws Swift_RfcComplianceException
203 * @see toString()
204 */
205 public function getFieldBody()
206 {
207 //Compute the string value of the header only if needed
208 if (is_null($this->getCachedValue()))
209 {
210 $this->setCachedValue($this->createMailboxListString($this->_mailboxes));
211 }
212 return $this->getCachedValue();
213 }
214
215 // -- Points of extension
216
217 /**
218 * Normalizes a user-input list of mailboxes into consistent key=>value pairs.
219 * @param string[] $mailboxes
220 * @return string[]
221 * @access protected
222 */
223 protected function normalizeMailboxes(array $mailboxes)
224 {
225 $actualMailboxes = array();
226
227 foreach ($mailboxes as $key => $value)
228 {
229 if (is_string($key)) //key is email addr
230 {
231 $address = $key;
232 $name = $value;
233 }
234 else
235 {
236 $address = $value;
237 $name = null;
238 }
239 $this->_assertValidAddress($address);
240 $actualMailboxes[$address] = $name;
241 }
242
243 return $actualMailboxes;
244 }
245
246 /**
247 * Produces a compliant, formatted display-name based on the string given.
248 * @param string $displayName as displayed
249 * @param boolean $shorten the first line to make remove for header name
250 * @return string
251 * @access protected
252 */
253 protected function createDisplayNameString($displayName, $shorten = false)
254 {
255 return $this->createPhrase($this, $displayName,
256 $this->getCharset(), $this->getEncoder(), $shorten
257 );
258 }
259
260 /**
261 * Creates a string form of all the mailboxes in the passed array.
262 * @param string[] $mailboxes
263 * @return string
264 * @throws Swift_RfcComplianceException
265 * @access protected
266 */
267 protected function createMailboxListString(array $mailboxes)
268 {
269 return implode(', ', $this->_createNameAddressStrings($mailboxes));
270 }
271
272 // -- Private methods
273
274 /**
275 * Return an array of strings conforming the the name-addr spec of RFC 2822.
276 * @param string[] $mailboxes
277 * @return string[]
278 * @access private
279 */
280 private function _createNameAddressStrings(array $mailboxes)
281 {
282 $strings = array();
283
284 foreach ($mailboxes as $email => $name)
285 {
286 $mailboxStr = $email;
287 if (!is_null($name))
288 {
289 $nameStr = $this->createDisplayNameString($name, empty($strings));
290 $mailboxStr = $nameStr . ' <' . $mailboxStr . '>';
291 }
292 $strings[] = $mailboxStr;
293 }
294
295 return $strings;
296 }
297
298 /**
299 * Throws an Exception if the address passed does not comply with RFC 2822.
300 * @param string $address
301 * @throws Exception If invalid.
302 * @access protected
303 */
304 private function _assertValidAddress($address)
305 {
306 if (!preg_match('/^' . $this->getGrammar('addr-spec') . '$/D',
307 $address))
308 {
309 throw new Swift_RfcComplianceException(
310 'Address in mailbox given [' . $address .
311 '] does not comply with RFC 2822, 3.6.2.'
312 );
313 }
314 }
315
316 }