All articles

Drupal Commerce receipt emails with an empty body: service destruct order

If Drupal Commerce order receipt emails start going out with an empty body after a core update, check the order in which services are destructed at the end of the request. The receipt can be rendered from a service's destruct() method, and if the theme registry has already destructed by then, the receipt template isn't found and the body comes out empty. The fix is to re-tag theme.registry with a very low needs_destruction priority so it is always the last destructable service.

What went wrong with the receipts

On a group of nonprofit membership sites that share one Drupal distribution, members pay for orders through Drupal Commerce and get a receipt email afterwards. After an update to a Drupal core 10.6 release, receipt emails started going out with an empty body.

The cause wasn't in the receipt template, the mail system or the order itself. A teammate traced it to the order of operations at the very end of the request, after the response has already been sent.

How Drupal destructs services at the end of a request

Drupal has a mechanism for work that should happen after the response is on its way to the browser. A service that implements DestructableInterface and is tagged needs_destruction gets its destruct() method called when the kernel terminates. Core uses it for things like writing caches that were filled during the request. Contrib modules use it too.

At container build time, a compiler pass collects every service with that tag, sorts them by the tag's priority attribute (higher runs first, default 0), and stores the list as a container parameter. On terminate, the kernel walks that list and calls destruct() on each service that was actually instantiated during the request.

Two services matter here:

  • Commerce Payment's order updater collects orders whose payments changed during the request and updates them in its destruct() method. On these sites, that update is the point where the receipt email gets rendered and sent.
  • The theme registry also destructs, and in doing so finishes with its runtime registry for the request. Once that has happened, theme hook lookups made afterwards in the same request no longer find the receipt template.

If the order updater destructs first, the receipt renders normally. If the theme registry goes first, the email is built against a registry that no longer knows the template, and the body is empty. Both services have the default priority, so which one wins is decided by the order they end up in the sorted list, which is not something anyone chose on purpose. A core update changed it.

How to make the theme registry destruct last

The team's fix was a service provider in a custom module that alters the existing definition: it removes the needs_destruction tag from theme.registry and adds it back with a very low priority, so it sorts after everything else. A minimal version, in a module called mymodule:

<?php

namespace Drupal\mymodule;

use Drupal\Core\DependencyInjection\ContainerBuilder;
use Drupal\Core\DependencyInjection\ServiceProviderBase;

class MymoduleServiceProvider extends ServiceProviderBase {

  public function alter(ContainerBuilder $container) {
    if ($container->hasDefinition('theme.registry')) {
      $definition = $container->getDefinition('theme.registry');
      $definition->clearTag('needs_destruction');
      $definition->addTag('needs_destruction', ['priority' => -1000]);
    }
  }

}

Drupal discovers the class by name: a module's service provider must be called <CamelCaseModuleName>ServiceProvider and live in the module's src folder. Rebuild the container (drush cr) after adding it.

Clearing the original tag first means the service carries exactly one needs_destruction tag, with the priority you meant, rather than two with different priorities.

What I like about this approach is that it states the real dependency. Anything that renders during destruction needs the theme registry, so the registry should be the last thing to go. It doesn't touch Commerce, the mail system or the template, and it keeps working if another module adds its own destructable service that also renders something.

Why it was reverted and then restored

The fix was briefly reverted on one site and then restored, with the commit message spelling out why: on that core release, the theme registry really does destruct before the order updater, and receipts go out empty without the change. That is worth writing down. A container alter like this looks like an odd, unexplained hack six months later, and the next person to see it will be tempted to delete it.

While in that area, the team found a second, unrelated problem. A theme negotiator that was meant to render the order receipt page in the site's front-end theme matched a route name that doesn't exist in Commerce. The real routes have .admin and .user suffixes, so the negotiator never applied. It was removed and replaced with one that matches the admin receipt route, so admins see the receipt with the site's own template. The lesson is general: a negotiator or route subscriber keyed on a route name fails silently when the name is wrong, so check the name against drush route or the module's routing file rather than guessing.

How to debug something like this

When output goes missing only in work that happens after the response, a few checks narrow it down quickly:

  • List the destructable services and their order by reading the kernel.destructable_services container parameter.
  • Find which destruct() method actually sends the email or does the rendering.
  • Check whether that code depends on any other destructable service, especially the theme registry or a cache collector.
  • Compare the order before and after the update that broke it.

Key takeaways

  • Drupal calls destruct() on services tagged needs_destruction after the response is sent, in priority order, higher first.
  • Commerce work done during destruction, such as receipt emails from payment order updates, can run after the theme registry has finished and render an empty template.
  • Re-tagging theme.registry with a very low needs_destruction priority in a service provider's alter() makes it destruct last.
  • Services with the same default priority have no meaningful order, so a core update can change it without warning.
  • Theme negotiators keyed on route names fail silently, so verify the exact route name before relying on one.