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 }
|