mail.inc 20.8 KB
Newer Older
1 2
<?php

3 4 5 6 7
/**
 * @file
 * API functions for processing and sending e-mail.
 */

8 9
/**
 * Auto-detect appropriate line endings for e-mails.
10
 *
11 12 13 14
 * $conf['mail_line_endings'] will override this setting.
 */
define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER_SOFTWARE'], 'Win32') !== FALSE ? "\r\n" : "\n");

15
/**
16
 * Composes and optionally sends an e-mail message.
17 18 19 20 21 22
 *
 * Sending an e-mail works with defining an e-mail template (subject, text
 * and possibly e-mail headers) and the replacement values to use in the
 * appropriate places in the template. Processed e-mail templates are
 * requested from hook_mail() from the module sending the e-mail. Any module
 * can modify the composed e-mail message array using hook_mail_alter().
23
 * Finally drupal_mail_system()->mail() sends the e-mail, which can
24 25
 * be reused if the exact same composed e-mail is to be sent to multiple
 * recipients.
26 27 28
 *
 * Finding out what language to send the e-mail with needs some consideration.
 * If you send e-mail to a user, her preferred language should be fine, so
29
 * use user_preferred_langcode(). If you send email based on form values
30 31
 * filled on the page, there are two additional choices if you are not
 * sending the e-mail to a user on the site. You can either use the language
32 33 34 35
 * used to generate the page or the site default language. See
 * language_default(). The former is good if sending e-mail to the person
 * filling the form, the later is good if you send e-mail to an address
 * previously set up (like contact addresses in a contact form).
36 37 38 39 40 41 42 43 44 45 46 47 48 49
 *
 * Taking care of always using the proper language is even more important
 * when sending e-mails in a row to multiple users. Hook_mail() abstracts
 * whether the mail text comes from an administrator setting or is
 * static in the source code. It should also deal with common mail tokens,
 * only receiving $params which are unique to the actual e-mail at hand.
 *
 * An example:
 *
 * @code
 *   function example_notify($accounts) {
 *     foreach ($accounts as $account) {
 *       $params['account'] = $account;
 *       // example_mail() will be called based on the first drupal_mail() parameter.
50
 *       drupal_mail('example', 'notice', $account->mail, user_preferred_langcode($account), $params);
51 52
 *     }
 *   }
Dries's avatar
Dries committed
53
 *
54
 *   function example_mail($key, &$message, $params) {
55
 *     $data['user'] = $params['account'];
56
 *     $options['langcode'] = $message['langcode'];
57
 *     user_mail_tokens($variables, $data, $options);
58 59
 *     switch($key) {
 *       case 'notice':
60 61 62 63 64 65
 *         // If the recipient can receive such notices by instant-message, do
 *         // not send by email.
 *         if (example_im_send($key, $message, $params)) {
 *           $message['send'] = FALSE;
 *           break;
 *         }
66 67
 *         $message['subject'] = t('Notification from !site', $variables, $options);
 *         $message['body'][] = t("Dear !username\n\nThere is new content available on the site.", $variables, $options);
68 69 70 71
 *         break;
 *     }
 *   }
 * @endcode
72
 *
73 74 75 76 77 78
 * Another example, which uses drupal_mail() to format a message for sending
 * later:
 *
 * @code
 *   $params = array('current_conditions' => $data);
 *   $to = 'user@example.com';
79
 *   $message = drupal_mail('example', 'notice', $to, $langcode, $params, FALSE);
80 81 82 83 84 85
 *   // Only add to the spool if sending was not canceled.
 *   if ($message['send']) {
 *     example_spool_message($message);
 *   }
 * @endcode
 *
86 87 88 89 90 91 92
 * @param $module
 *   A module name to invoke hook_mail() on. The {$module}_mail() hook will be
 *   called to complete the $message structure which will already contain common
 *   defaults.
 * @param $key
 *   A key to identify the e-mail sent. The final e-mail id for e-mail altering
 *   will be {$module}_{$key}.
93
 * @param $to
94
 *   The e-mail address or addresses where the message will be sent to. The
95
 *   formatting of this string must comply with RFC 2822. Some examples are:
96 97 98 99
 *   - user@example.com
 *   - user@example.com, anotheruser@example.com
 *   - User <user@example.com>
 *   - User <user@example.com>, Another User <anotheruser@example.com>
100 101
 * @param $langcode
 *   Language code to use to compose the e-mail.
102
 * @param $params
103
 *   (optional) parameters to build the e-mail.
104
 * @param $from
105
 *   Sets From to this value, if given.
106
 * @param $send
107 108 109 110
 *   If TRUE, drupal_mail() will call drupal_mail_system()->mail() to deliver
 *   the message, and store the result in $message['result']. Modules
 *   implementing hook_mail_alter() may cancel sending by setting
 *   $message['send'] to FALSE.
111
 *
112 113 114
 * @return
 *   The $message array structure containing all details of the
 *   message. If already sent ($send = TRUE), then the 'result' element
115 116 117
 *   will contain the success indicator of the e-mail, failure being already
 *   written to the watchdog. (Success means nothing more than the message being
 *   accepted at php-level, which still doesn't guarantee it to be delivered.)
118
 */
119
function drupal_mail($module, $key, $to, $langcode, $params = array(), $from = NULL, $send = TRUE) {
120 121 122 123 124
  $site_mail = config('system.site')->get('mail');
  if (empty($site_mail)) {
    $site_mail = ini_get('sendmail_from');
  }
  $default_from = $site_mail;
Dries's avatar
Dries committed
125

126 127
  // Bundle up the variables into a structured array for altering.
  $message = array(
128
    'id'       => $module . '_' . $key,
129 130
    'module'   => $module,
    'key'      => $key,
Dries's avatar
Dries committed
131
    'to'       => $to,
132
    'from'     => isset($from) ? $from : $default_from,
133
    'langcode' => $langcode,
134
    'params'   => $params,
135
    'send'     => TRUE,
136 137 138 139 140 141 142 143
    'subject'  => '',
    'body'     => array()
  );

  // Build the default headers
  $headers = array(
    'MIME-Version'              => '1.0',
    'Content-Type'              => 'text/plain; charset=UTF-8; format=flowed; delsp=yes',
144
    'Content-Transfer-Encoding' => '8Bit',
145
    'X-Mailer'                  => 'Drupal'
146 147
  );
  if ($default_from) {
148 149
    // To prevent e-mail from looking like spam, the addresses in the Sender and
    // Return-Path headers should have a domain authorized to use the originating
150 151
    // SMTP server.
    $headers['From'] = $headers['Sender'] = $headers['Return-Path'] = $default_from;
152 153
  }
  if ($from) {
154
    $headers['From'] = $from;
155
  }
156
  $message['headers'] = $headers;
Dries's avatar
Dries committed
157

158 159 160
  // Build the e-mail (get subject and body, allow additional headers) by
  // invoking hook_mail() on this module. We cannot use module_invoke() as
  // we need to have $message by reference in hook_mail().
161
  if (function_exists($function = $module . '_mail')) {
162 163
    $function($key, $message, $params);
  }
Dries's avatar
Dries committed
164

165
  // Invoke hook_mail_alter() to allow all modules to alter the resulting e-mail.
166 167
  drupal_alter('mail', $message);

168 169 170 171 172
  // Retrieve the responsible implementation for this message.
  $system = drupal_mail_system($module, $key);

  // Format the message body.
  $message = $system->format($message);
173 174 175

  // Optionally send e-mail.
  if ($send) {
176 177 178 179 180 181 182 183 184 185 186 187 188 189
    // The original caller requested sending. Sending was canceled by one or
    // more hook_mail_alter() implementations. We set 'result' to NULL, because
    // FALSE indicates an error in sending.
    if (empty($message['send'])) {
      $message['result'] = NULL;
    }
    // Sending was originally requested and was not canceled.
    else {
      $message['result'] = $system->mail($message);
      // Log errors.
      if (!$message['result']) {
        watchdog('mail', 'Error sending e-mail (from %from to %to).', array('%from' => $message['from'], '%to' => $message['to']), WATCHDOG_ERROR);
        drupal_set_message(t('Unable to send e-mail. Contact the site administrator if the problem persists.'), 'error');
      }
190
    }
191 192 193 194 195 196
  }

  return $message;
}

/**
197
 * Returns an object that implements Drupal\Core\Mail\MailInterface.
198
 *
199
 * Allows for one or more custom mail backends to format and send mail messages
200 201
 * composed using drupal_mail().
 *
202 203 204
 * An implementation needs to implement the following methods:
 * - format: Allows to preprocess, format, and postprocess a mail
 *   message before it is passed to the sending system. By default, all messages
205 206 207 208 209 210
 *   may contain HTML and are converted to plain-text by the
 *   Drupal\Core\Mail\PhpMail implementation. For example, an alternative
 *   implementation could override the default implementation and additionally
 *   sanitize the HTML for usage in a MIME-encoded e-mail, but still invoking
 *   the Drupal\Core\Mail\PhpMail implementation to generate an alternate
 *   plain-text version for sending.
211 212
 * - mail: Sends a message through a custom mail sending engine.
 *   By default, all messages are sent via PHP's mail() function by the
213
 *   Drupal\Core\Mail\PhpMail implementation.
214
 *
215
 * The selection of a particular implementation is controlled via the variable
216
 * 'mail_system', which is a keyed array.  The default implementation
217 218 219 220 221
 * is the class whose name is the value of 'default-system' key. A more specific
 * match first to key and then to module will be used in preference to the
 * default. To specificy a different class for all mail sent by one module, set
 * the class name as the value for the key corresponding to the module name. To
 * specificy a class for a particular message sent by one module, set the class
222
 * name as the value for the array key that is the message id, which is
223 224 225 226 227 228 229
 * "${module}_${key}".
 *
 * For example to debug all mail sent by the user module by logging it to a
 * file, you might set the variable as something like:
 *
 * @code
 * array(
230
 *   'default-system' => 'Drupal\Core\Mail\PhpMail',
231 232 233 234 235 236 237 238 239
 *   'user' => 'DevelMailLog',
 * );
 * @endcode
 *
 * Finally, a different system can be specified for a specific e-mail ID (see
 * the $key param), such as one of the keys used by the contact module:
 *
 * @code
 * array(
240
 *   'default-system' => 'Drupal\Core\Mail\PhpMail',
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
 *   'user' => 'DevelMailLog',
 *   'contact_page_autoreply' => 'DrupalDevNullMailSend',
 * );
 * @endcode
 *
 * Other possible uses for system include a mail-sending class that actually
 * sends (or duplicates) each message to SMS, Twitter, instant message, etc, or
 * a class that queues up a large number of messages for more efficient bulk
 * sending or for sending via a remote gateway so as to reduce the load
 * on the local server.
 *
 * @param $module
 *   The module name which was used by drupal_mail() to invoke hook_mail().
 * @param $key
 *   A key to identify the e-mail sent. The final e-mail ID for the e-mail
 *   alter hook in drupal_mail() would have been {$module}_{$key}.
257
 *
258
 * @return Drupal\Core\Mail\MailInterface
259
 */
260
function drupal_mail_system($module, $key) {
261 262 263
  $instances = &drupal_static(__FUNCTION__, array());

  $id = $module . '_' . $key;
264

265
  $configuration = variable_get('mail_system', array('default-system' => 'Drupal\Core\Mail\PhpMail'));
266 267 268 269 270 271 272 273

  // Look for overrides for the default class, starting from the most specific
  // id, and falling back to the module name.
  if (isset($configuration[$id])) {
    $class = $configuration[$id];
  }
  elseif (isset($configuration[$module])) {
    $class = $configuration[$module];
274 275
  }
  else {
276 277 278 279 280
    $class = $configuration['default-system'];
  }

  if (empty($instances[$class])) {
    $interfaces = class_implements($class);
281
    if (isset($interfaces['Drupal\Core\Mail\MailInterface'])) {
282
      $instances[$class] = new $class();
283 284
    }
    else {
285
      throw new Exception(t('Class %class does not implement interface %interface', array('%class' => $class, '%interface' => 'Drupal\Core\Mail\MailInterface')));
286 287
    }
  }
288 289 290
  return $instances[$class];
}

291
/**
292
 * Performs format=flowed soft wrapping for mail (RFC 3676).
293 294 295 296 297 298 299 300 301 302 303
 *
 * We use delsp=yes wrapping, but only break non-spaced languages when
 * absolutely necessary to avoid compatibility issues.
 *
 * We deliberately use LF rather than CRLF, see drupal_mail().
 *
 * @param $text
 *   The plain text to process.
 * @param $indent (optional)
 *   A string to indent the text with. Only '>' characters are repeated on
 *   subsequent wrapped lines. Others are replaced by spaces.
304 305 306
 *
 * @return
 *   The content of the email as a string with formatting applied.
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337
 */
function drupal_wrap_mail($text, $indent = '') {
  // Convert CRLF into LF.
  $text = str_replace("\r", '', $text);
  // See if soft-wrapping is allowed.
  $clean_indent = _drupal_html_to_text_clean($indent);
  $soft = strpos($clean_indent, ' ') === FALSE;
  // Check if the string has line breaks.
  if (strpos($text, "\n") !== FALSE) {
    // Remove trailing spaces to make existing breaks hard.
    $text = preg_replace('/ +\n/m', "\n", $text);
    // Wrap each line at the needed width.
    $lines = explode("\n", $text);
    array_walk($lines, '_drupal_wrap_mail_line', array('soft' => $soft, 'length' => strlen($indent)));
    $text = implode("\n", $lines);
  }
  else {
    // Wrap this line.
    _drupal_wrap_mail_line($text, 0, array('soft' => $soft, 'length' => strlen($indent)));
  }
  // Empty lines with nothing but spaces.
  $text = preg_replace('/^ +\n/m', "\n", $text);
  // Space-stuff special lines.
  $text = preg_replace('/^(>| |From)/m', ' $1', $text);
  // Apply indentation. We only include non-'>' indentation on the first line.
  $text = $indent . substr(preg_replace('/^/m', $clean_indent, $text), strlen($indent));

  return $text;
}

/**
338
 * Transforms an HTML string into plain text, preserving its structure.
339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
 *
 * The output will be suitable for use as 'format=flowed; delsp=yes' text
 * (RFC 3676) and can be passed directly to drupal_mail() for sending.
 *
 * We deliberately use LF rather than CRLF, see drupal_mail().
 *
 * This function provides suitable alternatives for the following tags:
 * <a> <em> <i> <strong> <b> <br> <p> <blockquote> <ul> <ol> <li> <dl> <dt>
 * <dd> <h1> <h2> <h3> <h4> <h5> <h6> <hr>
 *
 * @param $string
 *   The string to be transformed.
 * @param $allowed_tags (optional)
 *   If supplied, a list of tags that will be transformed. If omitted, all
 *   all supported tags are transformed.
354
 *
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
 * @return
 *   The transformed string.
 */
function drupal_html_to_text($string, $allowed_tags = NULL) {
  // Cache list of supported tags.
  static $supported_tags;
  if (empty($supported_tags)) {
    $supported_tags = array('a', 'em', 'i', 'strong', 'b', 'br', 'p', 'blockquote', 'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr');
  }

  // Make sure only supported tags are kept.
  $allowed_tags = isset($allowed_tags) ? array_intersect($supported_tags, $allowed_tags) : $supported_tags;

  // Make sure tags, entities and attributes are well-formed and properly nested.
  $string = _filter_htmlcorrector(filter_xss($string, $allowed_tags));

  // Apply inline styles.
372 373
  $string = preg_replace('!</?(em|i)((?> +)[^>]*)?>!i', '/', $string);
  $string = preg_replace('!</?(strong|b)((?> +)[^>]*)?>!i', '*', $string);
374 375 376 377

  // Replace inline <a> tags with the text of link and a footnote.
  // 'See <a href="http://drupal.org">the Drupal site</a>' becomes
  // 'See the Drupal site [1]' with the URL included as a footnote.
378
  _drupal_html_to_mail_urls(NULL, TRUE);
379
  $pattern = '@(<a[^>]+?href="([^"]*)"[^>]*?>(.+?)</a>)@i';
380 381 382 383 384 385
  $string = preg_replace_callback($pattern, '_drupal_html_to_mail_urls', $string);
  $urls = _drupal_html_to_mail_urls();
  $footnotes = '';
  if (count($urls)) {
    $footnotes .= "\n";
    for ($i = 0, $max = count($urls); $i < $max; $i++) {
386
      $footnotes .= '[' . ($i + 1) . '] ' . $urls[$i] . "\n";
387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
    }
  }

  // Split tags from text.
  $split = preg_split('/<([^>]+?)>/', $string, -1, PREG_SPLIT_DELIM_CAPTURE);
  // Note: PHP ensures the array consists of alternating delimiters and literals
  // and begins and ends with a literal (inserting $null as required).

  $tag = FALSE; // Odd/even counter (tag or no tag)
  $casing = NULL; // Case conversion function
  $output = '';
  $indent = array(); // All current indentation string chunks
  $lists = array(); // Array of counters for opened lists
  foreach ($split as $value) {
    $chunk = NULL; // Holds a string ready to be formatted and output.

    // Process HTML tags (but don't output any literally).
    if ($tag) {
      list($tagname) = explode(' ', strtolower($value), 2);
      switch ($tagname) {
        // List counters
        case 'ul':
          array_unshift($lists, '*');
          break;
        case 'ol':
          array_unshift($lists, 1);
          break;
        case '/ul':
        case '/ol':
          array_shift($lists);
          $chunk = ''; // Ensure blank new-line.
          break;

        // Quotation/list markers, non-fancy headers
        case 'blockquote':
          // Format=flowed indentation cannot be mixed with lists.
          $indent[] = count($lists) ? ' "' : '>';
          break;
        case 'li':
426
          $indent[] = isset($lists[0]) && is_numeric($lists[0]) ? ' ' . $lists[0]++ . ') ' : ' * ';
427 428 429 430 431 432 433 434 435 436 437 438 439
          break;
        case 'dd':
          $indent[] = '    ';
          break;
        case 'h3':
          $indent[] = '.... ';
          break;
        case 'h4':
          $indent[] = '.. ';
          break;
        case '/blockquote':
          if (count($lists)) {
            // Append closing quote for inline quotes (immediately).
440
            $output = rtrim($output, "> \n") . "\"\n";
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
            $chunk = ''; // Ensure blank new-line.
          }
          // Fall-through
        case '/li':
        case '/dd':
          array_pop($indent);
          break;
        case '/h3':
        case '/h4':
          array_pop($indent);
        case '/h5':
        case '/h6':
          $chunk = ''; // Ensure blank new-line.
          break;

        // Fancy headers
        case 'h1':
          $indent[] = '======== ';
          $casing = 'drupal_strtoupper';
          break;
        case 'h2':
          $indent[] = '-------- ';
          $casing = 'drupal_strtoupper';
          break;
        case '/h1':
        case '/h2':
          $casing = NULL;
          // Pad the line with dashes.
          $output = _drupal_html_to_text_pad($output, ($tagname == '/h1') ? '=' : '-', ' ');
          array_pop($indent);
          $chunk = ''; // Ensure blank new-line.
          break;

        // Horizontal rulers
        case 'hr':
          // Insert immediately.
477
          $output .= drupal_wrap_mail('', implode('', $indent)) . "\n";
478 479 480 481 482 483 484 485 486 487 488 489
          $output = _drupal_html_to_text_pad($output, '-');
          break;

        // Paragraphs and definition lists
        case '/p':
        case '/dl':
          $chunk = ''; // Ensure blank new-line.
          break;
      }
    }
    // Process blocks of text.
    else {
490 491 492 493
      // Convert inline HTML text to plain text; not removing line-breaks or
      // white-space, since that breaks newlines when sanitizing plain-text.
      $value = trim(decode_entities($value));
      if (drupal_strlen($value)) {
494 495 496 497 498 499 500 501 502 503 504
        $chunk = $value;
      }
    }

    // See if there is something waiting to be output.
    if (isset($chunk)) {
      // Apply any necessary case conversion.
      if (isset($casing)) {
        $chunk = $casing($chunk);
      }
      // Format it and apply the current indentation.
505
      $output .= drupal_wrap_mail($chunk, implode('', $indent)) . MAIL_LINE_ENDINGS;
506 507 508
      // Remove non-quotation markers from indentation.
      $indent = array_map('_drupal_html_to_text_clean', $indent);
    }
509

510 511 512 513 514 515 516 517
    $tag = !$tag;
  }

  return $output . $footnotes;
}

/**
 * Wraps words on a single line.
518 519
 *
 * Callback for array_walk() winthin drupal_wrap_mail().
520 521 522 523 524 525 526 527 528 529
 */
function _drupal_wrap_mail_line(&$line, $key, $values) {
  // Use soft-breaks only for purely quoted or unindented text.
  $line = wordwrap($line, 77 - $values['length'], $values['soft'] ? "  \n" : "\n");
  // Break really long words at the maximum width allowed.
  $line = wordwrap($line, 996 - $values['length'], $values['soft'] ? " \n" : "\n");
}

/**
 * Keeps track of URLs and replaces them with placeholder tokens.
530 531
 *
 * Callback for preg_replace_callback() within drupal_html_to_text().
532
 */
533
function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) {
534 535
  global $base_url, $base_path;
  static $urls = array(), $regexp;
536

537 538 539
  if ($reset) {
    // Reset internal URL list.
    $urls = array();
540
  }
541 542
  else {
    if (empty($regexp)) {
543
      $regexp = '@^' . preg_quote($base_path, '@') . '@';
544 545 546 547
    }
    if ($match) {
      list(, , $url, $label) = $match;
      // Ensure all URLs are absolute.
548 549
      $urls[] = strpos($url, '://') ? $url : preg_replace($regexp, $base_url . '/', $url);
      return $label . ' [' . count($urls) . ']';
550
    }
551 552 553 554 555
  }
  return $urls;
}

/**
556
 * Replaces non-quotation markers from a given piece of indentation with spaces.
557
 *
558
 * Callback for array_map() within drupal_html_to_text().
559 560 561 562 563 564
 */
function _drupal_html_to_text_clean($indent) {
  return preg_replace('/[^>]/', ' ', $indent);
}

/**
565
 * Pads the last line with the given character.
566
 *
567
 * @see drupal_html_to_text()
568 569 570 571 572 573 574 575
 */
function _drupal_html_to_text_pad($text, $pad, $prefix = '') {
  // Remove last line break.
  $text = substr($text, 0, -1);
  // Calculate needed padding space and add it.
  if (($p = strrpos($text, "\n")) === FALSE) {
    $p = -1;
  }
576
  $n = max(0, 79 - (strlen($text) - $p) - strlen($prefix));
577
  // Add prefix and padding, and restore linebreak.
578
  return $text . $prefix . str_repeat($pad, $n) . "\n";
579
}