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