function backdrop_mail_system

Returns an object that implements the MailSystemInterface interface.

Allows for one or more custom mail backends to format and send mail messages composed using backdrop_mail().

An implementation needs to implement the following methods:

• format: Allows to preprocess, format, and post-process a mail message before it is passed to the sending system. By default, all messages may contain HTML and are converted to plain-text by the DefaultMailSystem implementation. For example, an alternative implementation could override the default implementation and additionally sanitize the HTML for usage in a MIME-encoded email, but still invoking the DefaultMailSystem implementation to generate an alternate plain-text version for sending.
• mail: Sends a message through a custom mail sending engine. By default, all messages are sent via PHP's mail() function by the DefaultMailSystem implementation.

The selection of a particular implementation is controlled via the config 'system.mail', which contains a keyed array. The default implementation is the class whose name is the value of 'default-system' key. A more specific match first to key and then to module will be used in preference to the default. To specify a different class for all mail sent by one module, set the class name as the value for the key corresponding to the module name. To specify a class for a particular message sent by one module, set the class name 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-system' => 'DefaultMailSystem',
  'user' => 'DevelMailLog',
);

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

array(
  'default-system' => 'DefaultMailSystem',
  'user' => 'DevelMailLog',
  'contact_page_autoreply' => 'BackdropDevNullMailSend',
);

Other possible uses for system include a mail-sending class that actually sends (or duplicates) each message to SMS, Twitter, instant message, etc, or a class 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

$module: The module name which was used by backdrop_mail() to invoke hook_mail().

$key: A key to identify the email sent. The final email ID for the email alter hook in backdrop_mail() would have been {$module}_{$key}.

Return value

MailSystemInterface:

Throws

Exception

File

core/includes/mail.inc, line 262

API functions for processing and sending email.

Code

function backdrop_mail_system($module, $key) {
  $instances = &backdrop_static(__FUNCTION__, array());

  $id = $module . '_' . $key;

  $config = config('system.mail');

  // Look for overrides for the default class, starting from the most specific
  // id, and falling back to the module name.
  if ($config->get($id) !== NULL) {
    $class = $config->get($id);
  }
  elseif ($config->get($module) !== NULL) {
    $class = $config->get($module);
  }
  elseif ($config->get('default-system') !== NULL) {
    $class = $config->get('default-system');
  }
  else {
    $class = 'DefaultMailSystem';
  }

  if (empty($instances[$class])) {
    $interfaces = class_implements($class);
    if (isset($interfaces['MailSystemInterface'])) {
      $instances[$class] = new $class();
    }
    else {
      throw new Exception(t('Class %class does not implement interface %interface', array('%class' => $class, '%interface' => 'MailSystemInterface')));
    }
  }
  return $instances[$class];
}