annotate core/lib/Drupal/Core/Mail/MailManagerInterface.php @ 19:fa3358dc1485 tip

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