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