annotate core/lib/Drupal/Core/Mail/MailInterface.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 /**
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 }