Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

State API

Last updated on
22 November 2016

The State API provides a place for developers to store information about the system's state. State information differs from configuration in the following ways:

  • It is specific to an individual environment.
  • You will never want to deploy it between environments.
  • You can reset a system, losing all state. Its configuration remains.
  • So, use State API to store transient information, that is okay to lose after a reset. Think: CSRF tokens, tracking when something non-critical last happened …

A good example of state is the last time cron was run. This is specific to an environment and has no use in deployment. The state API is a simple system to store this information, which previously would have been stored in the variables system.

Typical usage:

  • Get a value:
    $val = \Drupal::state()->get('key');
  • Get multiple key/value pairs:
    $pairs = \Drupal::state()->getMultiple($keys);
  • Set a value:
  • Set multiple values:
  • Delete a value:

Data which needs to be edited by humans or needs to be shared between environments should use \Drupal::config() instead. See the Configuration API info.

Documentation for class \Drupal\Core\State\State, Drupal's default StateInterface implementation.

General State API documentation.