email_example.module

<?php


/**
 * @file
 * Example of how to use Drupal's mail API.
 */
use Drupal\Component\Utility\Html;

/**
 * @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 email (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 email templates that this module can
 * send. Each email 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 email being
    // sent. This $options array is used later in the t() calls for subject
    // and body to ensure the proper translation takes effect.
    $options = [
        '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('Email sent from @site-name', [
                '@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:', [
                '@name' => $account->getAccountName(),
            ], $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'][] = Html::escape($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 any way.
 * Converting the outgoing email to HTML 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 = [
        'langcode' => $message['langcode'],
    ];
    $signature = t("\n--\nMail altered by email_example module.", [], $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".
 */