Allow EmailBuilder plugin not linked to module name or config entity

Thanks for a clear explanation.

After some extra debugging, I found out that the plugin IDs should either be the same as a module name, or as a entity type.
That is not very clear from the documentation.

I'd welcome a patch to improve it. It's fairly clear on EmailFactoryInterface, but I agree that's rather late, because you already wrote the EmailBuilder by then.

The second EmailBuilder I wanted to add is linked with a specific content entity, so I thought I'd create a plugin with the entity type as ID, and has_entity annotation set to TRUE.

I have considered to allow the entity to be a content one. There might be some difficulties though. There can be 1000s of instances of a content entity which would lead to a corresponding huge number of different Mailer Policies. Content entities aren't required to have a string ID it can also be an int.

have checked the doc page https://www.drupal.org/docs/contributed-modules/symfony-mailer-0/develop... but that seems to be aimed towards letting my module work with symfony_mailer_bc, whereas I want it to work natively...

I agree, it would be great to have a doc page for creating a native email builder. I would be very happy if someone created it. There are currently two examples that I know of:

• TestEmailBuilder in this module
• Simplenews not yet committed but present in a patch for #3275129: Use Symfony Mailer API to send mails

However I would have preferred a separate EmailBuilder and separate policy configuration for each type of mail.

Did you try to create an EmailBuilder for a sub-type? If you look at EmailFactory::initEmail() then there is some code in this direction: it searches for a plug-in name based on the "suggestions" - which means first TYPE_SUBTYPE then TYPE. Probably this code has never been tested. I would welcome patches that fix it.

Maybe there should be a general $email_factory->newEmail()? Although that's probably nit-picking if I know I can use newModuleEmail().

The email would still need to have a type and the function needs a name that clarifies it is an alternative to newEntityEmail(). So it could be newTypedEmail() or newStringEmail(). Which leads to your next question....

Are there any plans to allow creating a simple Symfony Mailer EmailBuilder plugin / policy that is not hardwired to a module or config entity?

The old hook_mail system required $module and $key and this module is similar. I see a difficulty with allowing use of any string for the type: how would you ensure the string is unique? True, your strings all starts with your module name, but even so it's not guaranteed unique as for example someone might create a contrib module called mail_send and someone else mail_send_bulk.

Did you try to create an EmailBuilder for a sub-type? If you look at EmailFactory::initEmail() then there is some code in this direction: it searches for a plug-in name based on the "suggestions" - which means first TYPE_SUBTYPE then TYPE. Probably this code has never been tested. I would welcome patches that fix it.

Filed #3281730: Individual email builder class for every subtype.

I thought some more and I would like to fix this issue. It's the same for every plug-in - in theory there could be clash between plug-in ID in different modules but in practice it doesn't seem to be a problem.

I propose a fix as follows:

1. Add a label to the EmailBuilder annotation, which can be omitted if the plugin ID is an entity type or module name
2. Fix EmailBuilderManager::processDefinition(). The code to set $definition['provider'] is only needed for back-compatibility emails, so should be moved into symfony_mailer_bc_mailer_builder_info_alter, conditional on provider == symfony_mailer_bc.
3. Rename EmailFactoryInterface::sendModuleEmail(), my best idea is sendTypedEmail(string $type).

Fix EmailBuilderManager::processDefinition(). The code to set $definition['provider'] is only needed for back-compatibility emails, so should be moved into symfony_mailer_bc_mailer_builder_info_alter, conditional on provider == symfony_mailer_bc.

This is a very good Idea.

Please can people test and review?

It may have helped us a bit track down a bug with our integration if the release notes for alpha11 had the interface changes listed out... maybe

Could somebody clarify what the annotations should look like when there are multiple EmailBuilders for a single module, and what the sendTypedEmail() implementation should look like? I'm having trouble piecing it together from this issue and the documentation doesn't cover it as far as I can tell.

EDIT: Nevermind -- there was a silent error in my createParams that was breaking things. For anybody who comes across this in the future, here are my two classes

<?php

namespace Drupal\my_moduel\Plugin\EmailBuilder;

use Drupal\commerce_order\Entity\OrderInterface;
use Drupal\symfony_mailer\Address;
use Drupal\symfony_mailer\EmailInterface;
use Drupal\symfony_mailer\Processor\EmailBuilderBase;

/**
 * Defines the Email Builder plug-in for Store contact emails.
 *
 * @EmailBuilder(
 *   id = "my_moduel_new_order_notification",
 *   label = @Translation("New Order Notification"),
 *   sub_types = {
 *      "default" = @Translation("A new order notification to be sent to the store owner."),
 *   },
 *   common_adjusters = {},
 * )
 */
class NewOrderNotificationEmailBuilder extends EmailBuilderBase {

  /**
   * Saves the parameters for a newly created email.
   */
  public function createParams(EmailInterface $email, OrderInterface $order = NULL, Address $sender = NULL): void {
    assert($order != NULL);
    assert($sender != NULL);

    $email->setParams([
      'order' => $order,
      'sender' => $sender,
    ]);
  }

  /**
   * {@inheritdoc}
   */
  public function build(EmailInterface $email): void {
    /** @var OrderInterface $order */
    $order = $email->getParam('order');
    $store = $order->getStore();
    $recipient = new Address($store->getEmail(), $store->getName());

    $order = $email->getParam('order');
    $email->setTo($recipient)
      ->setFrom($email->getParam('sender'))
      ->setSubject('New order on Handcrafted')
      ->setBody([
        '#markup' => "You have a new order for {$order->getTotalPrice()->__toString()}. View this order from your dashboard.",
      ]);
  }
}

<?php

namespace Drupal\my_module\Plugin\EmailBuilder;

use Drupal\commerce_store\Entity\StoreInterface;
use Drupal\symfony_mailer\Address;
use Drupal\symfony_mailer\EmailInterface;
use Drupal\symfony_mailer\Processor\EmailBuilderBase;

/**
 * Defines the Email Builder plug-in for Store contact emails.
 *
 * @EmailBuilder(
 *   id = "my_module",
 *   label = @Translation("Contact Store"),
 *   sub_types = {
 *      "default" = @Translation("A generic contact email to be sent to a store."),
 *   },
 *   common_adjusters = {},
 * )
 */
class StoreEmailBuilder extends EmailBuilderBase {

  /**
   * Saves the parameters for a newly created email.
   */
  public function createParams(EmailInterface $email, StoreInterface $store = NULL, Address $sender = NULL, string $subject = NULL, string $message = NULL): void {
    assert($store != NULL);
    assert($message != NULL);
    assert($subject != NULL);
    assert($sender != NULL);

    $email->setParams([
      'store' => $store,
      'message' => $message,
      'subject' => $subject,
      'sender' => $sender,
    ]);
  }

  /**
   * {@inheritdoc}
   */
  public function build(EmailInterface $email): void {
    /** @var StoreInterface $store */
    $store = $email->getParam('store');
    $recipient = new Address($store->getEmail(), $store->getName());

    /** @phpstan-ignore-next-line */
    $markup = str_replace("\n", '<br />', $email->getParam('message'));

    $email->setTo($recipient)
      ->setFrom($email->getParam('sender'))
      ->setSubject($email->getParam('subject')) // @phpstan-ignore-line
      ->setBody([
        '#markup' => $markup,
      ]);
  }

}