Tracking State Changes in Drupal 11.3: New getValuesSetDuringRequest() Method

Published in Drupal Core 11.3.0

Drupal 11.3 introduces a new capability for module developers: a method that lets you track changes to state values within the lifecycle of a single HTTP request. This enhancement brings better transparency, logging, and security to operations involving state storage.

In this article, we’ll explore what changed, why it matters, and how you can use it.

✅ What’s New

A new method has been added to the Drupal\Core\State\StateInterface:

public function getValuesSetDuringRequest(string $key): ?array;

Its purpose is simple: tell you whether a state value changed during the current request, and if so, provide both the original and updated values.

Method return structure

If the key was modified, an associative array is returned:

If the state was not modified, the method returns NULL.

✅ Why This Matters

State values often control behaviors such as:

• Maintenance mode
• Feature toggles
• Temporary runtime flags

Previously, Drupal did not provide a built-in way to detect if such values were changed within the request. This made it hard to:

• Log changes
• Perform cleanup or reactions
• Audit configuration

Now, core and contrib modules can react to state mutations automatically.

✅ Example Use Case in Core

Drupal uses the method inside
Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.

This subscriber runs on kernel.terminate and logs whether maintenance mode was enabled or disabled during the request.

public function onTerminate(TerminateEvent $event): void {
  $values = $this->state->getValuesSetDuringRequest('system.maintenance_mode');

  if ($values && $values['original'] !== $values['value']) {
    if ($values['value']) {
      $this->logger->info('Maintenance mode enabled.');
    }
    else {
      $this->logger->info('Maintenance mode disabled.');
    }
  }
}

This is a great example of how Drupal can audit sensitive change events automatically.

✅ When You Must Update Your Code

If your custom class:

✔ extends Drupal\Core\State\State →
✅ You’re fine. No changes required.

If it:

❌ implements StateInterface but does not extend State →
➡️ You must implement this method, or Drupal will throw a fatal error.

This applies primarily to:

• Custom state managers
• Test doubles
• Third-party abstractions

✅ Basic Custom Implementation

If you maintain your own class implementing StateInterface, you must provide:

public function getValuesSetDuringRequest(string $key): ?array;

Example:

class MyState implements StateInterface {

  protected array $values = [];
  protected array $changedValues = [];

  public function set(string $key, $value) {
    if (!isset($this->changedValues[$key])) {
      $this->changedValues[$key] = [
        'original' => $this->get($key),
      ];
    }
    $this->values[$key] = $value;
    $this->changedValues[$key]['value'] = $value;
  }

  public function getValuesSetDuringRequest(string $key): ?array {
    return $this->changedValues[$key] ?? null;
  }

  public function get($key, $default = null) {
    return $this->values[$key] ?? $default;
  }

}

✅ Example Usage in a Custom Module

Let’s say your module enables a feature with a state flag.
You want to log when it changes.

public function onTerminate(TerminateEvent $event): void {
  $values = $this->state->getValuesSetDuringRequest('my_module.feature_enabled');

  if ($values && $values['original'] !== $values['value']) {
    $this->logger->info(
      'Feature flag changed from %old to %new',
      [
        '%old' => $values['original'], 
        '%new' => $values['value'],
      ]
    );
  }
}

✅ Practical Use Cases

This capability is particularly useful in projects requiring strict audit trails or traceable configuration changes.

✅ Summary

This improvement gives developers more power to react to changes and improves auditability across the Drupal ecosystem.