Emphasis correct usage of EmailFactoryInterface

Created on 29 March 2023, about 1 year ago
Updated 4 December 2023, 7 months ago

Problem/Motivation

On EmailFactoryInterface, the functions newTypedEmail() and newEntityEmail() are not recommended. There is already a comment for this, however there appears to still be some confusion, so it can be expanded. The reasons for this recommendation are:

  1. Good design: the code for sending an email is all together in one place on the EmailBuilder - similar to the old Drupal hook_mail() implementation, just a little cleaner, because we don't force the caller to calculate to and langcode. The implementation could be swapped to a different class with a hook.
  2. Any code that modifies the email directly runs at the wrong time - before any other email processor, even one that has set a highly negative weight to ensure that it runs first. Also it runs before the code to switch render context (in Mailer::send()) which risks leakage of metadata into the wrong context, possibly breaking caching.
  3. Any code that modifies the email directly might miss out on some future features that only work when the entire email is defined by the parameters. For example a user email need just 3 integers to define it: the type, subtype and uid. These parameters could be used for various purposes: to retry sending; to create a compact log record; to transfer sending to another process/daemon/thread; for caching.

Proposed resolution

Add documentation to EmailFactoryInterface and to the documentation guide.

Remaining tasks

User interface changes

API changes

Data model changes

πŸ“Œ Task
Status

Active

Version

1.0

Component

Documentation

Created by

πŸ‡¬πŸ‡§United Kingdom AdamPS

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Production build 0.69.0 2024