Using mail plugins

As I mentioned earlier, there is no UI in Drupal to select which plugin the mail manager should use for sending emails programmatically. It figures it out in the getInstance() method by checking the system.mail configuration object, and more specifically, the interface key inside that (which is an array).

By default, this array contains only one record, that is, 'default' => 'php_mail'. That means that, by default, all emails sent use the plugin with the php_mail ID. In order to get our plugin in the game, we have a few options:

• We can replace this value with our plugin ID, which means that all emails will be sent with our plugin
• We can add a new record with the key in the module_name_key_name format, which means that all emails sent for a module with a specific key (or template) will use that plugin
• We can add a new record with the key in the module_name format, which means that all emails sent for a module will use that plugin (regardless of their key)

For our example, we will set all emails sent from the hello_world module to use our new plugin. We can do this using the hook_install() implementation that runs whenever the module is installed:

/**
 * Implements hook_install().
 */
function hello_world_install() {
  $config = \Drupal::configFactory()->getEditable('system.mail');
  $mail_plugins = $config->get('interface');
  if (in_array('hello_world', array_keys($mail_plugins))) {
    return;
  }

  $mail_plugins['hello_world'] = 'hello_world_mail';
  $config->set('interface', $mail_plugins)->save();
}

As you can see, in this function, we load the configuration object as editable (so we can change it), and if we don't yet have a record with hello_world in the array of mail plugins we set it and map our plugin ID to it. Lastly, we save the object.

Install (and uninstall) hooks need to go inside a .install PHP file in the root of our module. So this function goes inside a new hello_world.install file. Also, if our module has been already enabled, we will need to first uninstall it and then install it again to get this function to fire.

The opposite of this function is hook_uninstall(), which goes in the same file and--expectedly--gets fired whenever the module is uninstalled. Since we don't want to change a site-wide configuration object and tie it to our module's plugin, we should implement this hook as well. Otherwise, if our module gets uninstalled, the mail system will fail because it will try to use a nonexistent plugin. So, let's tie up our loose ends:

/**
 * Implements hook_uninstall().
 */
function hello_world_uninstall() {
  $config = \Drupal::configFactory()->getEditable('system.mail');
  $mail_plugins = $config->get('interface');
  if (!in_array('hello_world', array_keys($mail_plugins))) {
    return;
  }

  unset($mail_plugins['hello_world']);
  $config->set('interface', $mail_plugins)->save();
}

As you can see, what we did here is basically the opposite. If the record we set previously exists, we unset it and save the configuration object, and that's it.

So, now, any mails sent programmatically for the hello_world module will use this plugin. Easy, right? However, since the plugin we wrote is not ready, the code you find in the repository will have the relevant line from the hook_install() implementation commented out so that we don't actually use it.