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