3 * Classes used to send e-mails
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.
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.
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
21 * @author <brion@pobox.com>
22 * @author <mail@tgries.de>
23 * @author Tim Starling
24 * @author Luke Welling lwelling@wikimedia.org
28 * Collection of static functions for sending mail
31 private static $mErrorString;
34 * Send mail using a PEAR mailer
36 * @param Mail_smtp $mailer
38 * @param string $headers
43 protected static function sendWithPear( $mailer, $dest, $headers, $body ) {
44 $mailResult = $mailer->send( $dest, $headers, $body );
46 // Based on the result return an error string,
47 if ( PEAR
::isError( $mailResult ) ) {
48 wfDebug( "PEAR::Mail failed: " . $mailResult->getMessage() . "\n" );
49 return Status
::newFatal( 'pear-mail-error', $mailResult->getMessage() );
51 return Status
::newGood();
56 * Creates a single string from an associative array
58 * @param array $headers Associative Array: keys are header field names,
59 * values are ... values.
60 * @param string $endl The end of line character. Defaults to "\n"
62 * Note RFC2822 says newlines must be CRLF (\r\n)
63 * but php mail naively "corrects" it and requires \n for the "correction" to work
67 static function arrayToHeaderString( $headers, $endl = PHP_EOL
) {
69 foreach ( $headers as $name => $value ) {
70 // Prevent header injection by stripping newlines from value
71 $value = self
::sanitizeHeaderValue( $value );
72 $strings[] = "$name: $value";
74 return implode( $endl, $strings );
78 * Create a value suitable for the MessageId Header
82 static function makeMsgId() {
83 global $wgSMTP, $wgServer;
85 $domainId = WikiMap
::getCurrentWikiDbDomain()->getId();
86 $msgid = uniqid( $domainId . ".", true /** for cygwin */ );
87 if ( is_array( $wgSMTP ) && isset( $wgSMTP['IDHost'] ) && $wgSMTP['IDHost'] ) {
88 $domain = $wgSMTP['IDHost'];
90 $url = wfParseUrl( $wgServer );
91 $domain = $url['host'];
93 return "<$msgid@$domain>";
97 * This function will perform a direct (authenticated) login to
98 * a SMTP Server to use for mail relaying if 'wgSMTP' specifies an
99 * array of parameters. It requires PEAR:Mail to do that.
100 * Otherwise it just uses the standard PHP 'mail' function.
102 * @param MailAddress|MailAddress[] $to Recipient's email (or an array of them)
103 * @param MailAddress $from Sender's email
104 * @param string $subject Email's subject.
105 * @param string|string[] $body Email's text or Array of two strings to be the text and html bodies
106 * @param array $options Keys:
107 * 'replyTo' MailAddress
108 * 'contentType' string default 'text/plain; charset=UTF-8'
109 * 'headers' array Extra headers to set
111 * @throws MWException
115 public static function send( $to, $from, $subject, $body, $options = [] ) {
116 global $wgAllowHTMLEmail;
118 if ( !isset( $options['contentType'] ) ) {
119 $options['contentType'] = 'text/plain; charset=UTF-8';
122 if ( !is_array( $to ) ) {
126 // mail body must have some content
128 // arbitrary but longer than Array or Object to detect casting error
130 // body must either be a string or an array with text and body
133 !is_array( $body ) &&
134 strlen( $body ) >= $minBodyLen
139 isset( $body['text'] ) &&
140 isset( $body['html'] ) &&
141 strlen( $body['text'] ) >= $minBodyLen &&
142 strlen( $body['html'] ) >= $minBodyLen
145 // if it is neither we have a problem
146 return Status
::newFatal( 'user-mail-no-body' );
149 if ( !$wgAllowHTMLEmail && is_array( $body ) ) {
150 // HTML not wanted. Dump it.
151 $body = $body['text'];
154 wfDebug( __METHOD__
. ': sending mail to ' . implode( ', ', $to ) . "\n" );
156 // Make sure we have at least one address
157 $has_address = false;
158 foreach ( $to as $u ) {
164 if ( !$has_address ) {
165 return Status
::newFatal( 'user-mail-no-addy' );
168 // give a chance to UserMailerTransformContents subscribers who need to deal with each
169 // target differently to split up the address list
170 if ( count( $to ) > 1 ) {
172 Hooks
::run( 'UserMailerSplitTo', [ &$to ] );
173 if ( $oldTo != $to ) {
174 $splitTo = array_diff( $oldTo, $to );
175 $to = array_diff( $oldTo, $splitTo ); // ignore new addresses added in the hook
176 // first send to non-split address list, then to split addresses one by one
177 $status = Status
::newGood();
179 $status->merge( self
::sendInternal(
180 $to, $from, $subject, $body, $options ) );
182 foreach ( $splitTo as $newTo ) {
183 $status->merge( self
::sendInternal(
184 [ $newTo ], $from, $subject, $body, $options ) );
190 return self
::sendInternal( $to, $from, $subject, $body, $options );
194 * Whether the PEAR Mail_mime library is usable. This will
195 * try and load it if it is not already.
199 private static function isMailMimeUsable() {
200 static $usable = null;
201 if ( $usable === null ) {
202 $usable = class_exists( 'Mail_mime' );
208 * Whether the PEAR Mail library is usable. This will
209 * try and load it if it is not already.
213 private static function isMailUsable() {
214 static $usable = null;
215 if ( $usable === null ) {
216 $usable = class_exists( 'Mail' );
223 * Helper function fo UserMailer::send() which does the actual sending. It expects a $to
224 * list which the UserMailerSplitTo hook would not split further.
225 * @param MailAddress[] $to Array of recipients' email addresses
226 * @param MailAddress $from Sender's email
227 * @param string $subject Email's subject.
228 * @param string|string[] $body Email's text or Array of two strings to be the text and html bodies
229 * @param array $options Keys:
230 * 'replyTo' MailAddress
231 * 'contentType' string default 'text/plain; charset=UTF-8'
232 * 'headers' array Extra headers to set
234 * @throws MWException
238 protected static function sendInternal(
245 global $wgSMTP, $wgEnotifMaxRecips, $wgAdditionalMailParams;
248 $replyto = $options['replyTo'] ??
null;
249 $contentType = $options['contentType'] ??
'text/plain; charset=UTF-8';
250 $headers = $options['headers'] ??
[];
252 // Allow transformation of content, such as encrypting/signing
254 if ( !Hooks
::run( 'UserMailerTransformContent', [ $to, $from, &$body, &$error ] ) ) {
256 return Status
::newFatal( 'php-mail-error', $error );
258 return Status
::newFatal( 'php-mail-error-unknown' );
263 * Forge email headers
264 * -------------------
268 * DO NOT add To: or Subject: headers at this step. They need to be
269 * handled differently depending upon the mailer we are going to use.
272 * PHP mail() first argument is the mail receiver. The argument is
273 * used as a recipient destination and as a To header.
275 * PEAR mailer has a recipient argument which is only used to
276 * send the mail. If no To header is given, PEAR will set it to
277 * to 'undisclosed-recipients:'.
279 * NOTE: To: is for presentation, the actual recipient is specified
280 * by the mailer using the Rcpt-To: header.
283 * PHP mail() second argument to pass the subject, passing a Subject
284 * as an additional header will result in a duplicate header.
286 * PEAR mailer should be passed a Subject header.
291 $headers['From'] = $from->toString();
292 $returnPath = $from->address
;
293 $extraParams = $wgAdditionalMailParams;
295 // Hook to generate custom VERP address for 'Return-Path'
296 Hooks
::run( 'UserMailerChangeReturnPath', [ $to, &$returnPath ] );
297 // Add the envelope sender address using the -f command line option when PHP mail() is used.
298 // Will default to the $from->address when the UserMailerChangeReturnPath hook fails and the
299 // generated VERP address when the hook runs effectively.
301 // PHP runs this through escapeshellcmd(). However that's not sufficient
302 // escaping (e.g. due to spaces). MediaWiki's email sanitizer should generally
303 // be good enough, but just in case, put in double quotes, and remove any
304 // double quotes present (" is not allowed in emails, so should have no
305 // effect, although this might cause apostrophees to be double escaped)
306 $returnPathCLI = '"' . str_replace( '"', '', $returnPath ) . '"';
307 $extraParams .= ' -f ' . $returnPathCLI;
309 $headers['Return-Path'] = $returnPath;
312 $headers['Reply-To'] = $replyto->toString();
315 $headers['Date'] = MWTimestamp
::getLocalInstance()->format( 'r' );
316 $headers['Message-ID'] = self
::makeMsgId();
317 $headers['X-Mailer'] = 'MediaWiki mailer';
318 $headers['List-Unsubscribe'] = '<' . SpecialPage
::getTitleFor( 'Preferences' )
319 ->getFullURL( '', false, PROTO_CANONICAL
) . '>';
321 // Line endings need to be different on Unix and Windows due to
322 // the bug described at https://core.trac.wordpress.org/ticket/2603
325 if ( is_array( $body ) ) {
326 // we are sending a multipart message
327 wfDebug( "Assembling multipart mime email\n" );
328 if ( !self
::isMailMimeUsable() ) {
329 wfDebug( "PEAR Mail_Mime package is not installed. Falling back to text email.\n" );
330 // remove the html body for text email fall back
331 $body = $body['text'];
333 // pear/mail_mime is already loaded by this point
334 if ( wfIsWindows() ) {
335 $body['text'] = str_replace( "\n", "\r\n", $body['text'] );
336 $body['html'] = str_replace( "\n", "\r\n", $body['html'] );
338 $mime = new Mail_mime( [
340 'text_charset' => 'UTF-8',
341 'html_charset' => 'UTF-8'
343 $mime->setTXTBody( $body['text'] );
344 $mime->setHTMLBody( $body['html'] );
345 $body = $mime->get(); // must call get() before headers()
346 $headers = $mime->headers( $headers );
349 if ( $mime === null ) {
350 // sending text only, either deliberately or as a fallback
351 if ( wfIsWindows() ) {
352 $body = str_replace( "\n", "\r\n", $body );
354 $headers['MIME-Version'] = '1.0';
355 $headers['Content-type'] = $contentType;
356 $headers['Content-transfer-encoding'] = '8bit';
359 // allow transformation of MIME-encoded message
360 if ( !Hooks
::run( 'UserMailerTransformMessage',
361 [ $to, $from, &$subject, &$headers, &$body, &$error ] )
364 return Status
::newFatal( 'php-mail-error', $error );
366 return Status
::newFatal( 'php-mail-error-unknown' );
370 $ret = Hooks
::run( 'AlternateUserMailer', [ $headers, $to, $from, $subject, $body ] );
371 if ( $ret === false ) {
372 // the hook implementation will return false to skip regular mail sending
373 return Status
::newGood();
374 } elseif ( $ret !== true ) {
375 // the hook implementation will return a string to pass an error message
376 return Status
::newFatal( 'php-mail-error', $ret );
379 if ( is_array( $wgSMTP ) ) {
380 // Check if pear/mail is already loaded (via composer)
381 if ( !self
::isMailUsable() ) {
382 throw new MWException( 'PEAR mail package is not installed' );
385 Wikimedia\
suppressWarnings();
387 // Create the mail object using the Mail::factory method
388 $mail_object = Mail
::factory( 'smtp', $wgSMTP );
389 if ( PEAR
::isError( $mail_object ) ) {
390 wfDebug( "PEAR::Mail factory failed: " . $mail_object->getMessage() . "\n" );
391 Wikimedia\restoreWarnings
();
392 return Status
::newFatal( 'pear-mail-error', $mail_object->getMessage() );
395 wfDebug( "Sending mail via PEAR::Mail\n" );
397 $headers['Subject'] = self
::quotedPrintable( $subject );
399 // When sending only to one recipient, shows it its email using To:
400 if ( count( $to ) == 1 ) {
401 $headers['To'] = $to[0]->toString();
404 // Split jobs since SMTP servers tends to limit the maximum
405 // number of possible recipients.
406 $chunks = array_chunk( $to, $wgEnotifMaxRecips );
407 foreach ( $chunks as $chunk ) {
408 $status = self
::sendWithPear( $mail_object, $chunk, $headers, $body );
409 // FIXME : some chunks might be sent while others are not!
410 if ( !$status->isOK() ) {
411 Wikimedia\restoreWarnings
();
415 Wikimedia\restoreWarnings
();
416 return Status
::newGood();
419 if ( count( $to ) > 1 ) {
420 $headers['To'] = 'undisclosed-recipients:;';
422 $headers = self
::arrayToHeaderString( $headers, $endl );
424 wfDebug( "Sending mail via internal mail() function\n" );
426 self
::$mErrorString = '';
427 $html_errors = ini_get( 'html_errors' );
428 ini_set( 'html_errors', '0' );
429 set_error_handler( 'UserMailer::errorHandler' );
432 foreach ( $to as $recip ) {
435 self
::quotedPrintable( $subject ),
441 } catch ( Exception
$e ) {
442 restore_error_handler();
446 restore_error_handler();
447 ini_set( 'html_errors', $html_errors );
449 if ( self
::$mErrorString ) {
450 wfDebug( "Error sending mail: " . self
::$mErrorString . "\n" );
451 return Status
::newFatal( 'php-mail-error', self
::$mErrorString );
452 } elseif ( !$sent ) {
453 // mail function only tells if there's an error
454 wfDebug( "Unknown error sending mail\n" );
455 return Status
::newFatal( 'php-mail-error-unknown' );
457 return Status
::newGood();
463 * Set the mail error message in self::$mErrorString
465 * @param int $code Error number
466 * @param string $string Error message
468 static function errorHandler( $code, $string ) {
469 self
::$mErrorString = preg_replace( '/^mail\(\)(\s*\[.*?\])?: /', '', $string );
473 * Strips bad characters from a header value to prevent PHP mail header injection attacks
474 * @param string $val String to be santizied
477 public static function sanitizeHeaderValue( $val ) {
478 return strtr( $val, [ "\r" => '', "\n" => '' ] );
482 * Converts a string into a valid RFC 822 "phrase", such as is used for the sender name
483 * @param string $phrase
486 public static function rfc822Phrase( $phrase ) {
487 // Remove line breaks
488 $phrase = self
::sanitizeHeaderValue( $phrase );
490 $phrase = str_replace( '"', '', $phrase );
491 return '"' . $phrase . '"';
495 * Converts a string into quoted-printable format
498 * From PHP5.3 there is a built in function quoted_printable_encode()
499 * This method does not duplicate that.
500 * This method is doing Q encoding inside encoded-words as defined by RFC 2047
501 * This is for email headers.
502 * The built in quoted_printable_encode() is for email bodies
503 * @param string $string
504 * @param string $charset
507 public static function quotedPrintable( $string, $charset = '' ) {
508 // Probably incomplete; see RFC 2045
509 if ( empty( $charset ) ) {
512 $charset = strtoupper( $charset );
513 $charset = str_replace( 'ISO-8859', 'ISO8859', $charset ); // ?
515 $illegal = '\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\xff=';
516 $replace = $illegal . '\t ?_';
517 if ( !preg_match( "/[$illegal]/", $string ) ) {
520 $out = "=?$charset?Q?";
521 $out .= preg_replace_callback( "/([$replace])/",
522 function ( $matches ) {
523 return sprintf( "=%02X", ord( $matches[1] ) );