Change record status: 
Project: 
Introduced in branch: 
8.x
Introduced in version: 
8.x
Description: 

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.

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.

Drupal 7

<?php
//  /core/includes/menu.inc
function menu_get_item($path = NULL, $router_item = NULL) {
if (
variable_get('menu_rebuild_needed', FALSE) || !variable_get('menu_masks', array())) {
//  /core/includes/menu.inc
function menu_router_rebuild() {
variable_del('menu_rebuild_needed');
//  /core/modules/search/search.admin.inc
function search_admin_settings_submit($form, &$form_state) {
variable_set('menu_rebuild_needed', TRUE);
?>

Drupal 8

<?php
//  /core/includes/menu.inc
function menu_get_item($path = NULL, $router_item = NULL) {
if (
Drupal::state()->get('menu_rebuild_needed', FALSE) || !variable_get('menu_masks', array())) {
//  /core/includes/menu.inc
function menu_router_rebuild() {
Drupal::state()->delete('menu_rebuild_needed');
//  /core/modules/search/search.admin.inc
function search_admin_settings_submit($form, &$form_state) {
Drupal::state()->set('menu_rebuild_needed', TRUE);
?>

Calls to Drupal::state->get() can have an optional default value provided as the second parameter:

<?php
// Will return 0 as the default value if the 'system.cron_last' key is not retrieved. This normal default value is NULL.
Drupal::state->get('system.cron_last', 0);
// Same idea, but default to an array.
Drupal::state->get('field.field.deleted', array());
?>
Impacts: 
Site builders, administrators, editors
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Generic online documentation done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done
Details: 

Documentation pages can be found here http://drupal.org/node/1787278
Related documentation for Configuration API http://drupal.org/node/1667894