Drupal 8  8.0.2
MailManager Class Reference
Inheritance diagram for MailManager:

Public Member Functions

 __construct (\Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler, ConfigFactoryInterface $config_factory, LoggerChannelFactoryInterface $logger_factory, TranslationInterface $string_translation)
 
 getInstance (array $options)
 
 mail ($module, $key, $to, $langcode, $params=array(), $reply=NULL, $send=TRUE)
 
- Public Member Functions inherited from DefaultPluginManager
 __construct ($subdir,\Traversable $namespaces, ModuleHandlerInterface $module_handler, $plugin_interface=NULL, $plugin_definition_annotation_name= 'Drupal\Component\Annotation\Plugin')
 
 setCacheBackend (CacheBackendInterface $cache_backend, $cache_key, array $cache_tags=array())
 
 getDefinitions ()
 
 clearCachedDefinitions ()
 
 useCaches ($use_caches=FALSE)
 
 processDefinition (&$definition, $plugin_id)
 
- Public Member Functions inherited from PluginManagerBase
 getDefinition ($plugin_id, $exception_on_invalid=TRUE)
 
 getDefinitions ()
 
 createInstance ($plugin_id, array $configuration=array())
 
 getInstance (array $options)
 
- Public Member Functions inherited from DiscoveryInterface
 hasDefinition ($plugin_id)
 

Protected Attributes

 $configFactory
 
 $loggerFactory
 
 $instances = array()
 
- Protected Attributes inherited from DefaultPluginManager
 $cacheKey
 
 $cacheTags = array()
 
 $alterHook
 
 $subdir
 
 $moduleHandler
 
 $defaults = array()
 
 $pluginDefinitionAnnotationName
 
 $pluginInterface
 
 $namespaces
 
- Protected Attributes inherited from PluginManagerBase
 $discovery
 
 $factory
 
 $mapper
 

Additional Inherited Members

- Protected Member Functions inherited from DefaultPluginManager
 alterInfo ($alter_hook)
 
 getCachedDefinitions ()
 
 setCachedDefinitions ($definitions)
 
 getDiscovery ()
 
 getFactory ()
 
 findDefinitions ()
 
 alterDefinitions (&$definitions)
 
 providerExists ($provider)
 
- Protected Member Functions inherited from PluginManagerBase
 getDiscovery ()
 
 getFactory ()
 

Detailed Description

Provides a Mail plugin manager.

See Also
Plugin API

Constructor & Destructor Documentation

__construct ( \Traversable  $namespaces,
CacheBackendInterface  $cache_backend,
ModuleHandlerInterface  $module_handler,
ConfigFactoryInterface  $config_factory,
LoggerChannelFactoryInterface  $logger_factory,
TranslationInterface  $string_translation 
)

Constructs the MailManager object.

Parameters
\Traversable$namespacesAn object that implements which contains the root paths keyed by the corresponding namespace to look for plugin implementations.
\Drupal\Core\Cache\CacheBackendInterface$cache_backendCache backend instance to use.
\Drupal\Core\Extension\ModuleHandlerInterface$module_handlerThe module handler to invoke the alter hook with.
\Drupal\Core\Config\ConfigFactoryInterface$config_factoryThe configuration factory.
\Drupal\Core\Logger\LoggerChannelFactoryInterface$logger_factoryThe logger channel factory.
\Drupal\Core\StringTranslation\TranslationInterface$string_translationThe string translation service.

References DefaultPluginManager\alterInfo(), Drupal\configFactory(), and DefaultPluginManager\setCacheBackend().

Here is the call graph for this function:

Member Function Documentation

getInstance ( array  $options)

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$optionsAn array with the following key/value pairs:
  • module: (string) The module name which was used by ->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}.
Returns
A mail plugin instance.
Exceptions
\Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException

Implements MapperInterface.

References Drupal\configFactory(), and PluginManagerBase\createInstance().

Referenced by MailManager\mail().

Here is the call graph for this function:

Here is the caller graph for this function:

mail (   $module,
  $key,
  $to,
  $langcode,
  $params = array(),
  $reply = NULL,
  $send = TRUE 
)

{Composes and optionally sends an email message.Sending an email works with defining an email template (subject, text and possibly email headers) and the replacement values to use in the appropriate places in the template. Processed email templates are requested from hook_mail() from the module sending the email. Any module can modify the composed email message array using hook_mail_alter(). Finally ::service('plugin.manager.mail')->mail() sends the email, which can be reused if the exact same composed email is to be sent to multiple recipients.Finding out what language to send the email with needs some consideration. If you send email to a user, her preferred language should be fine, so use user_preferred_langcode(). If you send email based on form values filled on the page, there are two additional choices if you are not sending the email to a user on the site. You can either use the language used to generate the page or the site default language. See Drupal::getDefaultLanguage(). The former is good if sending email to the person filling the form, the later is good if you send email to an address previously set up (like contact addresses in a contact form).Taking care of always using the proper language is even more important when sending emails in a row to multiple users. Hook_mail() abstracts whether the mail text comes from an administrator setting or is static in the source code. It should also deal with common mail tokens, only receiving $params which are unique to the actual email at hand.An example:

function example_notify($accounts) {
foreach ($accounts as $account) {
$params['account'] = $account;
// example_mail() will be called based on the first
// MailManagerInterface->mail() parameter.
\Drupal::service('plugin.manager.mail')->mail('example', 'notice', $account->mail, user_preferred_langcode($account), $params);
}
}
function example_mail($key, &$message, $params) {
$data['user'] = $params['account'];
$options['langcode'] = $message['langcode'];
user_mail_tokens($variables, $data, $options);
switch($key) {
case 'notice':
// If the recipient can receive such notices by instant-message, do
// not send by email.
if (example_im_send($key, $message, $params)) {
$message['send'] = FALSE;
break;
}
$message['subject'] = t('Notification from @site', $variables, $options);
$message['body'][] = t("Dear @username\n\nThere is new content available on the site.", $variables, $options);
break;
}
}
Another example, which uses MailManagerInterface->mail() to format a message for sending later:
$params = array('current_conditions' => $data);
$to = 'user@example.com';
$message = \Drupal::service('plugin.manager.mail')->mail('example', 'notice', $to, $langcode, $params, FALSE);
// Only add to the spool if sending was not canceled.
if ($message['send']) {
example_spool_message($message);
}
Parameters
string$moduleA module name to invoke hook_mail() on. The {$module}_mail() hook will be called to complete the $message structure which will already contain common defaults.
string$keyA key to identify the email sent. The final message ID for email altering will be {$module}_{$key}.
string$toThe email address or addresses where the message will be sent to. The formatting of this string will be validated with the PHP email validation filter. Some examples are:
string$langcodeLanguage code to use to compose the email.
array$params(optional) Parameters to build the email.
string | null$replyOptional email address to be used to answer.
bool$sendIf TRUE, call an implementation of ->mail() to deliver the message, and store the result in $message['result']. Modules implementing hook_mail_alter() may cancel sending by setting $message['send'] to FALSE.
Returns
array The $message array structure containing all details of the message. If already sent ($send = TRUE), then the 'result' element will contain the success indicator of the email, failure being already written to the watchdog. (Success means nothing more than the message being accepted at php-level, which still doesn't guarantee it to be delivered.)
}

Implements MailManagerInterface.

References Drupal\configFactory(), MailManager\getInstance(), Drupal\moduleHandler(), PlainTextOutput\renderFromHtml(), and t().

Here is the call graph for this function:


The documentation for this class was generated from the following file: