<?php

/**
 * @file
 * Example of how to use Drupal's mail API.
 */

use Drupal\Component\Utility\SafeMarkup;

/**
 * @defgroup email_example Example: Email
 * @{
 * Example of how to use Drupal's mail API.
 *
 * This example module provides two different examples of the Drupal email API:
 *  - Defines a simple contact form and shows how to use MailManager::mail()
 *    to send an e-mail (defined in hook_mail()) when the form is submitted.
 *  - Shows how modules can alter emails defined by other Drupal modules or
 *    core using hook_mail_alter by attaching a custom signature before
 *    they are sent.
 */

/**
 * Implements hook_mail().
 *
 * This hook defines a list of possible e-mail templates that this module can
 * send. Each e-mail is given a unique identifier, or 'key'.
 *
 * $message comes in with some standard properties already set: 'to' address,
 * 'from' address, and a set of default 'headers' from MailManager::mail(). The
 * goal of hook_mail() is to set the message's 'subject' and 'body' properties,
 * as well as make any adjustments to the headers that are necessary.
 *
 * The $params argument is an array which can hold any additional data required
 * to build the mail subject and body; for example, user-entered form data, or
 * some context information as to where the mail request came from.
 *
 * Note that hook_mail() is not actually a hook. It is only called for a single
 * module, the module named in the first argument of MailManager::mail(). So
 * it's a callback of a type, but not a hook.
 */
function email_example_mail($key, &$message, $params) {
  // Each message is associated with a language, which may or may not be the
  // current user's selected language, depending on the type of e-mail being
  // sent. This $options array is used later in the t() calls for subject
  // and body to ensure the proper translation takes effect.
  $options = array(
    'langcode' => $message['langcode'],
  );

  switch ($key) {
    // Send a simple message from the contact form.
    case 'contact_message':
      $from = \Drupal::config('system.site')->get('mail');
      $message['subject'] = t('E-mail sent from @site-name', array('@site-name' => $from), $options);
      // Note that the message body is an array, not a string.

      $account = \Drupal::currentUser();
      $message['body'][] = t('@name sent you the following message:', array('@name' => $account->getUsername()), $options);
      // Because this is just user-entered text, we do not need to translate it.
      // Since user-entered text may have unintentional HTML entities in it like
      // '<' or '>', we need to make sure these entities are properly escaped,
      // as the body will later be transformed from HTML to text, meaning
      // that a normal use of '<' will result in truncation of the message.
      $message['body'][] = SafeMarkup::checkPlain($params['message']);
      break;
  }
}

/**
 * Implements hook_mail_alter().
 *
 * This function is not required to send an email using Drupal's mail system.
 *
 * hook_mail_alter() provides an interface to alter any aspect of email sent by
 * Drupal. You can use this hook to add a common site footer to all outgoing
 * email, add extra header fields, and/or modify the email in anyway. HTML-izing
 * the outgoing email is one possibility.
 */
function email_example_mail_alter(&$message) {
  // For the purpose of this example, modify all the outgoing messages and
  // attach a site signature. The signature will be translated to the language
  // in which message was built.
  $options = array(
    'langcode' => $message['langcode'],
  );

  $signature = t("\n--\nMail altered by email_example module.", array(), $options);
  if (is_array($message['body'])) {
    $message['body'][] = $signature;
  }
  else {
    // Some modules use the body as a string, erroneously.
    $message['body'] .= $signature;
  }
}

/**
 * @} End of "defgroup email_example".
 */