aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Mail/MailInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Mail;
   4
   5 /**
   6  * Defines an interface for pluggable mail back-ends.
   7  *
   8  * @see \Drupal\Core\Annotation\Mail
   9  * @see \Drupal\Core\Mail\MailManager
  10  * @see plugin_api
  11  */
  12 interface MailInterface {
  13
  14   /**
  15    * Formats a message prior to sending.
  16    *
  17    * Allows to preprocess, format, and postprocess a mail message before it is
  18    * passed to the sending system. By default, all messages may contain HTML and
  19    * are converted to plain-text by the Drupal\Core\Mail\Plugin\Mail\PhpMail
  20    * implementation. For example, an alternative implementation could override
  21    * the default implementation and also sanitize the HTML for usage in a MIME-
  22    * encoded email, but still invoking the Drupal\Core\Mail\Plugin\Mail\PhpMail
  23    * implementation to generate an alternate plain-text version for sending.
  24    *
  25    * @param array $message
  26    *   A message array, as described in hook_mail_alter().
  27    *
  28    * @return array
  29    *   The formatted $message.
  30    *
  31    * @see \Drupal\Core\Mail\MailManagerInterface
  32    */
  33   public function format(array $message);
  34
  35   /**
  36    * Sends a message composed by \Drupal\Core\Mail\MailManagerInterface->mail().
  37    *
  38    * @param array $message
  39    *   Message array with at least the following elements:
  40    *   - id: A unique identifier of the email type. Examples: 'contact_user_copy',
  41    *     'user_password_reset'.
  42    *   - to: The mail address or addresses where the message will be sent to.
  43    *     The formatting of this string will be validated with the
  44    *     @link http://php.net/manual/filter.filters.validate.php PHP email validation filter. @endlink
  45    *     Some examples:
  46    *     - user@example.com
  47    *     - user@example.com, anotheruser@example.com
  48    *     - User <user@example.com>
  49    *     - User <user@example.com>, Another User <anotheruser@example.com>
  50    *   - subject: Subject of the email to be sent. This must not contain any
  51    *     newline characters, or the mail may not be sent properly. The subject
  52    *     is converted to plain text by the mail plugin manager.
  53    *   - body: Message to be sent. Accepts both CRLF and LF line-endings.
  54    *     Email bodies must be wrapped. For smart plain text wrapping you can use
  55    *     \Drupal\Core\Mail\MailFormatHelper::wrapMail() .
  56    *   - headers: Associative array containing all additional mail headers not
  57    *     defined by one of the other parameters.  PHP's mail() looks for Cc and
  58    *     Bcc headers and sends the mail to addresses in these headers too.
  59    *
  60    * @return bool
  61    *   TRUE if the mail was successfully accepted for delivery, otherwise FALSE.
  62    */
  63   public function mail(array $message);
  64
  65 }