Drupal Patterns

Apply all row-reducing conditions to an entity query before calling `->pager()`

Source: Adam Bramley, alexpott, Rafael Payan in #2722307
Tags: reliability, maintainability

Pager correctness depends on every condition that narrows the result set being applied inside the query, not in PHP after loading. When code runs ->pager(N) on an entity query and then filters the loaded objects in a loop (for example, checking isRevisionTranslationAffected() or hasTranslation() on each result), the pager counts the raw database rows, not the displayed subset. This produces pages with fewer items than expected and can produce empty pages mid-sequence.

Move all such conditions into the entity query using ->condition() before the ->pager() call. For translatable revision lists, add conditions on the entity type's langcode key and revision_translation_affected key. The pager then counts exactly the rows that will be displayed, and pagination behaves correctly across all pages.

Before

// Query fetches 50 revisions; PHP then discards non-affecting ones.
$vids = $storage->getQuery()
  ->allRevisions()
  ->condition('nid', $node->id())
  ->sort('vid', 'DESC')
  ->pager(50)
  ->execute();

$rows = [];
foreach (array_keys($vids) as $vid) {
  $revision = $storage->loadRevision($vid);
  if (!$revision->hasTranslation($langcode)) {
    continue;
  }
  $translation = $revision->getTranslation($langcode);
  if (!$translation->isRevisionTranslationAffected()) {
    continue;
  }
  $rows[] = $this->buildRow($translation);
}

After

// Filtering happens inside the query so the pager counts only displayable rows.
$entityType = $node->getEntityType();
$vids = $storage->getQuery()
  ->allRevisions()
  ->condition($entityType->getKey('id'), $node->id())
  ->condition($entityType->getKey('langcode'), $langcode)
  ->condition($entityType->getKey('revision_translation_affected'), '1')
  ->sort($entityType->getKey('revision'), 'DESC')
  ->pager(50)
  ->execute();

$rows = [];
foreach (array_keys($vids) as $vid) {
  $revision = $storage->loadRevision($vid);
  $rows[] = $this->buildRow($revision->getTranslation($langcode));
}

Detection

Detect PHP files that call isRevisionTranslationAffected() as a method on a loaded entity object; these are candidates where translation filtering may be happening in PHP instead of inside the query. Cross-check each hit to see whether a pager( call is present in the same file.

rg "isRevisionTranslationAffected\(\)" --type php -l

True positives: method calls inside a foreach over query results that also use pager(). False positives: the interface/trait declaration, uses inside storage internals (ContentEntityStorageBase), and legitimate non-paged filtering. The broader principle (any row-reducing PHP filter applied after a paged query) cannot be caught by a single command; review any loop over paged query results for continue or if guards that skip rows.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Replace deprecated `uri_callback` on entity types with link templates or a route provider

Source: eojthebrave, longwave, godotislate in #2667040
Tags: deprecation, maintainability

Entity types that declare uri_callback in their PHP attribute or annotation are using a mechanism deprecated in Drupal 11.4.0 and scheduled for removal in Drupal 13.0.0. The callback was once the only way to provide a canonical URL for an entity, but the links array (link templates) and route providers have replaced it for both simple and complex routing needs.

Replace uri_callback with a links array in the entity type attribute or annotation, declaring named routes such as canonical, edit-form, and delete-form. For entity types with complex or dynamic URL patterns that cannot use static route templates, implement EntityRouteProviderInterface and register it under handlers in the entity type definition. Drupal's routing layer resolves the correct URL automatically in both cases. See the change record at https://www.drupal.org/node/3575062 for migration details.

Before

#[ContentEntityType(
  id: 'article',
  label: new TranslatableMarkup('Article'),
  uri_callback: 'article_uri',
)]

After

#[ContentEntityType(
  id: 'article',
  label: new TranslatableMarkup('Article'),
  links: [
    'canonical' => '/article/{article}',
    'edit-form' => '/article/{article}/edit',
    'delete-form' => '/article/{article}/delete',
  ],
)]

Detection

Run this command to find all PHP files that assign a non-null string to uri_callback in an entity type attribute or annotation:

rg 'uri_callback\s*[=:]\s*["\x27]' --type php -l

True positives are entity type class files with a named callback string. False positives include core's own attribute class constructors (which declare uri_callback = NULL as a parameter default) and EntityType.php; those will not match the quoted-value pattern above.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Remove redundant `role` attributes from HTML5 semantic landmark elements in Twig templates

Source: BarisW, Andrew Macpherson, Mike Gifford, Liam Morland, Mike Herchel, Benjamin Mullins in #2655794
Tags: accessibility, maintainability

HTML5 semantic elements carry implicit ARIA landmark roles that all modern browsers expose automatically to assistive technologies. Adding an explicit role attribute that matches the element's built-in implicit role is redundant: role="main" on <main>, role="navigation" on <nav>, role="complementary" on <aside>, role="banner" on <header>, and role="contentinfo" on <footer> are all no-ops in any browser that supports HTML5. They also trigger HTML validation warnings.

These attributes were originally required for Internet Explorer 11, which did not pass implicit landmark roles to accessibility APIs. With IE11 support dropped in Drupal 10, they became dead weight. Remove the matching role attribute from the element tag in Twig templates. Keep role attributes when they override or supplement an element's implicit role, or when placed on non-semantic containers like <div> or <span> that have no implicit role of their own.

Before

<header role="banner">
<main role="main" class="layout-main">
  <aside class="sidebar" role="complementary">
  <footer role="contentinfo">

After

<header>
<main class="layout-main">
  <aside class="sidebar">
  <footer>

Detection

Run:

rg -n '(<main[^>]*role="main"|<nav[^>]*role="navigation"|<aside[^>]*role="complementary"|<header[^>]*role="banner"|<footer[^>]*role="contentinfo")' --glob '*.twig'

Each match is a true positive: the element already provides the listed implicit ARIA role. Ignore results in stable9 or similar legacy-compatibility themes that deliberately preserve these attributes for backward compatibility with CSS and JS selectors in downstream code.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Pop RequestStack in a `finally` block after every manual push in sub-request handlers

Source: cpj, larowlan, alexpott in #2613044
Tags: reliability, maintainability

When stack middleware or a custom sub-request handler pushes a request onto RequestStack, it must pop that entry in a finally block after the inner kernel returns. Without a finally guard, any thrown exception or early return leaves a stale entry on the stack. Stale entries cause cache contexts such as route to resolve against the wrong request, which can serve poisoned cached responses to subsequent visitors.

The rule: every explicit requestStack->push() must have a matching requestStack->pop() in a finally block scoped to the same call. For Drupal's main request the pop can be deferred to DrupalKernel::terminate() because terminate-time subscribers still need the request. For sub-requests ($type !== MAIN_REQUEST) pop immediately in finally after the inner handle() call returns. Drupal core's KernelPreHandle middleware is the authoritative example of this pattern.

Before

public function handle(Request $request, $type = self::MAIN_REQUEST, $catch = TRUE): Response {
  $this->drupalKernel->preHandle($request);
  return $this->httpKernel->handle($request, $type, $catch);
}

After

public function handle(Request $request, $type = self::MAIN_REQUEST, $catch = TRUE): Response {
  $this->drupalKernel->preHandle($request);
  try {
    return $this->httpKernel->handle($request, $type, $catch);
  }
  finally {
    if ($type !== self::MAIN_REQUEST) {
      $this->requestStack->pop();
    }
  }
}

Detection

Detect with:

rg -n 'requestStack->push\b' --type php

Review each hit: if the push() call is not followed by a pop() inside a finally block in the same method, it is a true positive. Test files that push a mock request for setup without a corresponding pop are likely false positives and can be skipped.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Add new service dependencies to plugin base classes with a nullable constructor parameter and deprecation fallback

Source: larowlan, alexpott, catch in #2571679
Tags: deprecation, reliability, maintainability

When a plugin base class needs a new service dependency, do not add it as a required constructor parameter immediately. Instead, append it as ?ServiceClass $service = NULL to __construct(), fall back to \Drupal::service() when it is null, and emit a @trigger_error() deprecation. Always pass the real service from the container in create().

This preserves backward compatibility for every custom or contrib module that subclasses the base class and overrides __construct(). Adding a required parameter immediately breaks those subclasses at runtime with no warning. The optional nullable parameter gives downstream authors a full major-version window to update their signatures. In the next major version, remove the fallback branch and make the parameter required. Drupal core uses this pattern consistently whenever a new injectable dependency is retrofitted onto an existing plugin base class.

Before

public function __construct(
  array $configuration,
  $plugin_id,
  $plugin_definition,
  ViewExecutableFactory $executable_factory,
  EntityStorageInterface $storage,
  AccountInterface $user,
) {
  parent::__construct($configuration, $plugin_id, $plugin_definition);
}

public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
  return new static(
    $configuration, $plugin_id, $plugin_definition,
    $container->get('views.executable'),
    $container->get('entity_type.manager')->getStorage('view'),
    $container->get('current_user'),
  );
}

After

public function __construct(
  array $configuration,
  $plugin_id,
  $plugin_definition,
  ViewExecutableFactory $executable_factory,
  EntityStorageInterface $storage,
  AccountInterface $user,
  ?ContextualLinksHelper $contextual_links = NULL,
) {
  if (!$contextual_links) {
    @trigger_error('Calling ' . __METHOD__ . '() without the $contextual_links argument is deprecated in drupal:11.4.0 and will be required in drupal:13.0.0. See https://www.drupal.org/node/3382344', E_USER_DEPRECATED);
    $contextual_links = \Drupal::service(ContextualLinksHelper::class);
  }
  $this->contextualLinks = $contextual_links;
  parent::__construct($configuration, $plugin_id, $plugin_definition);
}

public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
  return new static(
    $configuration, $plugin_id, $plugin_definition,
    $container->get('views.executable'),
    $container->get('entity_type.manager')->getStorage('view'),
    $container->get('current_user'),
    $container->get(ContextualLinksHelper::class),
  );
}

Detection

Detect: search for constructors that already use this pattern (or are missing it when they should have it).

rg "without the \\\$.*argument is deprecated" --include="*.php" .

True positives are base-class constructors that added a new service using the nullable-with-fallback technique. False positives are essentially zero because this exact message format is used only for this pattern. When reviewing a patch that adds a required parameter to a base-class constructor without a nullable fallback, that is a missing instance of this pattern.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Replace deprecated `filter_formats()` and related procedural functions with `FilterFormatRepositoryInterface`

Source: catch, Berdir, larowlan in #2536594
Tags: deprecation, maintainability

Six procedural functions for working with filter formats are deprecated in Drupal 11.4 and removed in Drupal 13: filter_formats(), filter_formats_reset(), filter_get_roles_by_format(), filter_get_formats_by_role(), filter_default_format(), and filter_fallback_format(). Inject FilterFormatRepositoryInterface instead and call the corresponding methods: getAllFormats(), getFormatsForAccount($account), getFormatsByRole($rid), getDefaultFormat($account), and getFallbackFormatId(). The single exception is filter_get_roles_by_format($format), which maps to $format->getRoles() on the entity itself. To reset the cache, invalidate the entity type list cache tags rather than calling filter_formats_reset().

These functions relied on drupal_static() and were unswappable in tests. The repository service is injectable and keyed to a stable interface. Note that filter_formats() was especially error-prone: passing an $account silently narrowed the result to only the formats that account could access, while omitting it returned all formats. The repository splits this into two explicitly named methods, eliminating silent behavioral divergence.

Before

// Procedural calls, deprecated in 11.4, removed in 13.0.
$all_formats = filter_formats();
$user_formats = filter_formats($account);
$default_format = filter_default_format($account);
$fallback_id = filter_fallback_format();
$roles = filter_get_roles_by_format($format);
$formats = filter_get_formats_by_role($rid);
filter_formats_reset();

After

// Inject the service and call the repository methods.
$repo = \Drupal::service(FilterFormatRepositoryInterface::class);
$all_formats = $repo->getAllFormats();
$user_formats = $repo->getFormatsForAccount($account);
$default_format = $repo->getDefaultFormat($account);
$fallback_id = $repo->getFallbackFormatId();
$roles = $format->getRoles();
$formats = $repo->getFormatsByRole($rid);
\Drupal::entityTypeManager()->getDefinition('filter_format')->getListCacheTags();

Detection

Detect:

rg 'filter_formats\s*\(|filter_formats_reset\s*\(|filter_default_format\s*\(|filter_fallback_format\s*\(|filter_get_roles_by_format\s*\(|filter_get_formats_by_role\s*\(' --type php

True positives are direct call-sites in contrib or custom code. Exclude core/modules/filter/filter.module (the deprecated stubs themselves) and docblock-only lines to reduce noise.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Declare cross-module update ordering with `hook_update_dependencies()`

Source: hchonov, alexpott, catch, larowlan in #1894286
Tags: reliability, maintainability

When a module's update hook depends on schema changes, config keys, or data rows introduced by a different module's update hook, declare that ordering constraint explicitly using hook_update_dependencies() in the .install file. Return an array entry keyed as $dependencies['your_module'][your_update_number] naming the prerequisite module and update number.

Drupal's update dependency graph respects only explicitly declared constraints; it does not guarantee any implicit ordering between modules. Relying on alphabetical module name, installation sequence, or assumed "system always runs first" behavior is fragile and breaks silently across Drupal version upgrades. Omitting the declaration can cause your update to run before its prerequisite, producing cryptic failures or silent data corruption. The reverse direction — declaring that your update must run before another module's update — should be avoided: any site that ran the later update before your code shipped will silently ignore the constraint.

Before

// mymodule.install
// No ordering declared; silently assumes system_update_11201 has run.
function mymodule_update_11001(): void {
  \Drupal::database()->schema()->addField('router', 'new_col', [...]);
}

After

// mymodule.install
function mymodule_update_dependencies(): array {
  // mymodule_update_11001 must run after the router table is updated by system.
  $dependencies['mymodule'][11001] = ['system' => 11201];
  return $dependencies;
}

function mymodule_update_11001(): void {
  \Drupal::database()->schema()->addField('router', 'new_col', [...]);
}

Detection

Detect .install files that have update hooks but no _update_dependencies declaration — these are candidates to audit for hidden cross-module ordering assumptions:

comm -23 \
  <(rg "function \w+_update_\d+" --include="*.install" -l | sort) \
  <(rg "function \w+_update_dependencies" --include="*.install" -l | sort)

True positives are files whose update hooks access schema, config, or data owned by another module (check for table names, config prefixes, or service calls that belong to a different module). False positives are self-contained update hooks with no cross-module data access.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Use `#config_target` on form elements to eliminate manual config saving in `submitForm()`

Source: DieterHolvoet, alexpott in #1503146
Tags: maintainability, reliability

In a ConfigFormBase subclass, adding '#config_target' => 'config_name:key.path' to a form element tells the framework to read and write that config value automatically. The form's buildForm() populates the field from config, and submitForm() saves it back, with no custom code required. When every field uses #config_target, the submitForm() override can be removed entirely and getEditableConfigNames() becomes redundant (use RedundantEditableConfigNamesTrait).

Manual submitForm() overrides that fetch $this->config(...) and call ->set(...) then ->save() are error-prone boilerplate: they duplicate field names, must be kept in sync with buildForm(), and often bypass the config schema validation that #config_target applies automatically.

Before

public function buildForm(array $form, FormStateInterface $form_state) {
  $config = $this->config('system.site');
  $form['site_name'] = [
    '#type' => 'textfield',
    '#default_value' => $config->get('name'),
  ];
  return parent::buildForm($form, $form_state);
}

public function submitForm(array &$form, FormStateInterface $form_state) {
  $this->config('system.site')
    ->set('name', $form_state->getValue('site_name'))
    ->save();
  parent::submitForm($form, $form_state);
}

After

public function buildForm(array $form, FormStateInterface $form_state) {
  $form['site_name'] = [
    '#type' => 'textfield',
    '#config_target' => 'system.site:name',
  ];
  return parent::buildForm($form, $form_state);
}

Detection

Find ConfigFormBase subclasses that still use a manual submitForm() for config saving (candidates to convert):

rg -rl "extends ConfigFormBase" /path/to/project --glob "*.php" | xargs rg -l "function submitForm"

Each result is a form class that overrides submitForm(); inspect whether it calls $this->config(...)->set(...)->save() on values taken directly from $form_state. Those are strong candidates for replacement with #config_target. Classes that perform validation or side-effects in submitForm() beyond pure config saving are false positives for this pattern.

This content is AI-generated and may contain errors. See Drupal Digests for more.

Use service decorator with `decorates:` and `#[AutowireDecorated]` to extend a core service across module boundaries

Source: DieterHolvoet, alexpott in #1503146
Tags: maintainability, reliability

When a module needs to extend the behavior of a core service but cannot introduce a reverse dependency, use Symfony's service decorator pattern. Declare decorates: original.service.id in your module's services.yml and inject the inner service with the #[AutowireDecorated] attribute in your class constructor. The container will transparently replace the original service with your decorator everywhere it is used.

This avoids the coupling problems of subclassing or overriding service definitions. The decorated class implements the same interface, delegates unchanged methods to $this->decorated, and only extends the methods it needs to augment. Because the decorator lives in a separate module, the core module never gains a dependency on the extending module. Cache the result of expensive delegate calls when the decorated method is called frequently.

Before

services:
  mymodule.path_matcher:
    class: Drupal\mymodule\MyPathMatcher
    arguments: ['@path.matcher', '@path_alias.manager']

After

services:
  Drupal\mymodule\MyPathMatcher:
    public: false
    decorates: path.matcher

Detection

Detect existing decorator registrations to understand usage or find candidate services to decorate:

rg "decorates:" /path/to/project --glob "*.yml" -l

True positives are decorates: some.service.id lines in services.yml files. To find ConfigFormBase subclasses that manually save config in submitForm() and could migrate to #config_target, see the companion pattern. False positives are rare; YAML comments containing the word "decorates" are the only likely noise.

This content is AI-generated and may contain errors. See Drupal Digests for more.