1<?php
2/**
3 * Classes used to send e-mails
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 * @author <brion@pobox.com>
22 * @author <mail@tgries.de>
23 * @author Tim Starling
24 * @author Luke Welling lwelling@wikimedia.org
25 */
26
27/**
28 * Stores a single person's name and email address.
29 * These are passed in via the constructor, and will be returned in SMTP
30 * header format when requested.
31 *
32 * @newable
33 */
34class MailAddress {
35	/**
36	 * @var string
37	 */
38	public $name;
39
40	/**
41	 * @var string
42	 */
43	public $realName;
44
45	/**
46	 * @var string
47	 */
48	public $address;
49
50	/**
51	 * @stable to call
52	 *
53	 * @param string $address String with an email address
54	 * @param string|null $name Human-readable name if a string address is given
55	 * @param string|null $realName Human-readable real name if a string address is given
56	 */
57	public function __construct( $address, $name = null, $realName = null ) {
58		$this->address = strval( $address );
59		$this->name = strval( $name );
60		$this->realName = strval( $realName );
61	}
62
63	/**
64	 * Create a new MailAddress object for the given user
65	 *
66	 * @since 1.24
67	 * @param User $user
68	 * @return MailAddress
69	 */
70	public static function newFromUser( User $user ) {
71		return new MailAddress( $user->getEmail(), $user->getName(), $user->getRealName() );
72	}
73
74	/**
75	 * Return formatted and quoted address to insert into SMTP headers
76	 * @return string
77	 */
78	public function toString() {
79		if ( !$this->address ) {
80			return '';
81		}
82
83		# PHP's mail() implementation under Windows is somewhat shite, and
84		# can't handle "Joe Bloggs <joe@bloggs.com>" format email addresses,
85		# so don't bother generating them
86		if ( $this->name === '' || wfIsWindows() ) {
87			return $this->address;
88		}
89
90		global $wgEnotifUseRealName;
91		$name = ( $wgEnotifUseRealName && $this->realName !== '' ) ? $this->realName : $this->name;
92		$quoted = UserMailer::quotedPrintable( $name );
93		// Must only be quoted if string does not use =? encoding (T191931)
94		if ( $quoted === $name ) {
95			$quoted = '"' . addslashes( $quoted ) . '"';
96		}
97
98		return "$quoted <{$this->address}>";
99	}
100
101	public function __toString() {
102		return $this->toString();
103	}
104}
105