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

   1 <?php
   2
   3 namespace Drupal\Core\Mail;
   4
   5 use Drupal\Component\Plugin\PluginManagerInterface;
   6
   7 /**
   8  * Provides an interface for sending mail.
   9  */
  10 interface MailManagerInterface extends PluginManagerInterface {
  11
  12   /**
  13    * Composes and optionally sends an email message.
  14    *
  15    * Sending an email works with defining an email template (subject, text and
  16    * possibly email headers) and the replacement values to use in the
  17    * appropriate places in the template. Processed email templates are requested
  18    * from hook_mail() from the module sending the email. Any module can modify
  19    * the composed email message array using hook_mail_alter(). Finally
  20    * \Drupal::service('plugin.manager.mail')->mail() sends the email, which can
  21    * be reused if the exact same composed email is to be sent to multiple
  22    * recipients.
  23    *
  24    * Finding out what language to send the email with needs some consideration.
  25    * If you send email to a user, her preferred language should be fine, so use
  26    * \Drupal\Core\Session\AccountInterface::getPreferredAdminLangcode(). If you
  27    * send email based on form values filled on the page, there are two
  28    * additional choices if you are not sending the email to a user on the site.
  29    * You can either use the language used to generate the page or the site
  30    * default language. See
  31    * Drupal\Core\Language\LanguageManagerInterface::getDefaultLanguage(). The
  32    * former is good if sending email to the person filling the form, the later
  33    * is good if you send email to an address previously set up (like contact
  34    * addresses in a contact form).
  35    *
  36    * Taking care of always using the proper language is even more important when
  37    * sending emails in a row to multiple users. Hook_mail() abstracts whether
  38    * the mail text comes from an administrator setting or is static in the
  39    * source code. It should also deal with common mail tokens, only receiving
  40    * $params which are unique to the actual email at hand.
  41    *
  42    * An example:
  43    *
  44    * @code
  45    *   function example_notify($accounts) {
  46    *     foreach ($accounts as $account) {
  47    *       $params['account'] = $account;
  48    *       // example_mail() will be called based on the first
  49    *       // MailManagerInterface->mail() parameter.
  50    *       \Drupal::service('plugin.manager.mail')->mail('example', 'notice', $account->mail, $langcode, $params);
  51    *     }
  52    *   }
  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    *     switch($key) {
  59    *       case 'notice':
  60    *         // If the recipient can receive such notices by instant-message, do
  61    *         // not send by email.
  62    *         if (example_im_send($key, $message, $params)) {
  63    *           $message['send'] = FALSE;
  64    *           break;
  65    *         }
  66    *         $message['subject'] = t('Notification from @site', $variables, $options);
  67    *         $message['body'][] = t("Dear @username\n\nThere is new content available on the site.", $variables, $options);
  68    *         break;
  69    *     }
  70    *   }
  71    * @endcode
  72    *
  73    * Another example, which uses MailManagerInterface->mail() to format a
  74    * message for sending later:
  75    *
  76    * @code
  77    *   $params = array('current_conditions' => $data);
  78    *   $to = 'user@example.com';
  79    *   $message = \Drupal::service('plugin.manager.mail')->mail('example', 'notice', $to, $langcode, $params, FALSE);
  80    *   // Only add to the spool if sending was not canceled.
  81    *   if ($message['send']) {
  82    *     example_spool_message($message);
  83    *   }
  84    * @endcode
  85    *
  86    * @param string $module
  87    *   A module name to invoke hook_mail() on. The {$module}_mail() hook will be
  88    *   called to complete the $message structure which will already contain
  89    *   common defaults.
  90    * @param string $key
  91    *   A key to identify the email sent. The final message ID for email altering
  92    *   will be {$module}_{$key}.
  93    * @param string $to
  94    *   The email address or addresses where the message will be sent to. The
  95    *   formatting of this string will be validated with the
  96    *   @link http://php.net/manual/filter.filters.validate.php PHP email validation filter. @endlink
  97    *   Some examples are:
  98    *   - user@example.com
  99    *   - user@example.com, anotheruser@example.com
 100    *   - User <user@example.com>
 101    *   - User <user@example.com>, Another User <anotheruser@example.com>
 102    * @param string $langcode
 103    *   Language code to use to compose the email.
 104    * @param array $params
 105    *   (optional) Parameters to build the email.
 106    * @param string|null $reply
 107    *   Optional email address to be used to answer.
 108    * @param bool $send
 109    *   If TRUE, call an implementation of
 110    *   \Drupal\Core\Mail\MailInterface->mail() to deliver the message, and
 111    *   store the result in $message['result']. Modules implementing
 112    *   hook_mail_alter() may cancel sending by setting $message['send'] to
 113    *   FALSE.
 114    *
 115    * @return array
 116    *   The $message array structure containing all details of the message. If
 117    *   already sent ($send = TRUE), then the 'result' element will contain the
 118    *   success indicator of the email, failure being already written to the
 119    *   watchdog. (Success means nothing more than the message being accepted at
 120    *   php-level, which still doesn't guarantee it to be delivered.)
 121    */
 122   public function mail($module, $key, $to, $langcode, $params = [], $reply = NULL, $send = TRUE);
 123
 124 }