function MailManager::getInstance

Same name in other branches
  1. 8.9.x core/lib/Drupal/Core/Mail/MailManager.php \Drupal\Core\Mail\MailManager::getInstance()
  2. 10 core/lib/Drupal/Core/Mail/MailManager.php \Drupal\Core\Mail\MailManager::getInstance()
  3. 11.x core/lib/Drupal/Core/Mail/MailManager.php \Drupal\Core\Mail\MailManager::getInstance()

Overrides PluginManagerBase::getInstance().

Returns an instance of the mail plugin to use for a given message ID.

The selection of a particular implementation is controlled via the config 'system.mail.interface', which is a keyed array. The default implementation is the mail plugin whose ID is the value of 'default' key. A more specific match first to key and then to module will be used in preference to the default. To specify a different plugin for all mail sent by one module, set the plugin ID as the value for the key corresponding to the module name. To specify a plugin for a particular message sent by one module, set the plugin ID as the value for the array key that is the message ID, which is "{$module}_{$key}".

For example to debug all mail sent by the user module by logging it to a file, you might set the variable as something like:

array(
    'default' => 'php_mail',
    'user' => 'devel_mail_log',
);

Finally, a different system can be specified for a specific message ID (see the $key param), such as one of the keys used by the contact module:

array(
    'default' => 'php_mail',
    'user' => 'devel_mail_log',
    'contact_page_autoreply' => 'null_mail',
);

Other possible uses for system include a mail-sending plugin that actually sends (or duplicates) each message to SMS, Twitter, instant message, etc, or a plugin that queues up a large number of messages for more efficient bulk sending or for sending via a remote gateway so as to reduce the load on the local server.

Parameters

array $options: An array with the following key/value pairs:

  • module: (string) The module name which was used by \Drupal\Core\Mail\MailManagerInterface->mail() to invoke hook_mail().
  • key: (string) A key to identify the email sent. The final message ID is a string represented as {$module}_{$key}.

Return value

\Drupal\Core\Mail\MailInterface A mail plugin instance.

Throws

\Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException

Overrides PluginManagerBase::getInstance

1 call to MailManager::getInstance()
MailManager::doMail in core/lib/Drupal/Core/Mail/MailManager.php
Composes and optionally sends an email message.

File

core/lib/Drupal/Core/Mail/MailManager.php, line 145

Class

MailManager
Provides a Mail plugin manager.

Namespace

Drupal\Core\Mail

Code

public function getInstance(array $options) {
    $module = $options['module'];
    $key = $options['key'];
    $message_id = $module . '_' . $key;
    $configuration = $this->configFactory
        ->get('system.mail')
        ->get('interface');
    // Look for overrides for the default mail plugin, starting from the most
    // specific message_id, and falling back to the module name.
    if (isset($configuration[$message_id])) {
        $plugin_id = $configuration[$message_id];
    }
    elseif (isset($configuration[$module])) {
        $plugin_id = $configuration[$module];
    }
    else {
        $plugin_id = $configuration['default'];
    }
    if (empty($this->instances[$plugin_id])) {
        $this->instances[$plugin_id] = $this->createInstance($plugin_id);
    }
    return $this->instances[$plugin_id];
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.