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

Drupal 8 introduces the concept of configuration entities (or configurables) that leverage the entity system's CRUD and pluggable storage functionality. The main difference between configuration entities and Drupal 7-style content entities is that configuration entities use the configuration system for storage, rather than the database. They differ from plain configuration in that they are typically user-created, and often need to fire and respond to hooks. Examples of potential configuration entities include:

  • Content types
  • Views
  • Taxonomy vocabularies
  • Contact forms
  • Image styles
  • etc.

To define a new configuration entity type, extend the ConfigEntityBase class and define an interface that extends ConfigEntityInterface.

Configuration entities do not currently support revisions (RevisionableInterface), the Entity Translation API (TranslatableInterface) (but they can be translated through the config translation API) nor are they typed data (TypedDataInterface), which means they can't have fields.

In my_module/src/MyConfigurableInterface.php:

<?php
/**
 * @file
 * Contains \Drupal\my_module\MyConfigurableInterface.
 */

namespace Drupal\my_module;

use
Drupal\Core\Config\Entity\ConfigEntityInterface;

/**
 * Provides an interface defining my configurable data object.
 */
interface MyConfigurableInterface extends ConfigEntityInterface {
 
// Any public methods your class has should be here as well.
}
?>

In my_module/src/Entity/MyConfigurable.php:

<?php
/**
 * @file
 * Contains \Drupal\my_module\Entity\MyConfigurable.
 */

namespace Drupal\my_module\Entity;

use
Drupal\Core\Config\Entity\ConfigEntityBase;
use
Drupal\my_module\MyConfigurableInterface;

/**
 * Defines a MyConfigurable configuration entity.
 *
 * @ConfigEntityType(
 *   id = "my_configurable",
 *   label = @Translation("My configurable data object"),
 *   controllers = {
 *     "storage" = "Drupal\Core\Config\Entity\ConfigEntityStorage"
 *   },
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label",
 *   }
 * )
 */
class MyConfigurable extends ConfigEntityBase implements MyConfigurableInterface {

 
/**
   * The machine-readable ID for the configurable.
   */
 
public $id;

 
/**
   * The human-readable label for the configurable.
   */
 
public $label;

 
// Override methods from ConfigEntityBase as needed.

}
?>

For guidelines on converting existing user-created configuration data to configuration entities, see How to upgrade data to configuration entities.

Configuration schema

To store configuration entities, a configuration schema is required by default. A schema offers translation integration and ensures type persistence and type casting. See the API documentation Configuration schema/metadata.

Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not 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