Configuration API

Information about the Configuration API.

The Configuration API is one of several methods in Drupal for storing information. See the Information types topic for an overview of the different types of information. The sections below have more information about the configuration API; see for more details.

Configuration storage

In Drupal, there is a concept of the "active" configuration, which is the configuration that is currently in use for a site. The storage used for the active configuration is configurable: it could be in the database, in files in a particular directory, or in other storage backends; the default storage is in the database. Module developers must use the configuration API to access the active configuration, rather than being concerned about the details of where and how it is stored.

Configuration is divided into individual objects, each of which has a unique name or key. Some modules will have only one configuration object, typically called 'mymodule.settings'; some modules will have many. Within a configuration object, configuration settings have data types (integer, string, Boolean, etc.) and settings can also exist in a nested hierarchy, known as a "mapping".

Configuration can also be overridden on a global, per-language, or per-module basis. See for more information.

Configuration YAML files

Whether or not configuration files are being used for the active configuration storage on a particular site, configuration files are always used for:

  • Defining the default configuration for a module, which is imported to the active storage when the module is enabled. Note that changes to this default configuration after a module is already enabled have no effect; to make a configuration change after a module is enabled, you would need to uninstall/reinstall or use a hook_update_N() function.
  • Exporting and importing configuration.

The file storage format for configuration information in Drupal is YAML files. Configuration is divided into files, each containing one configuration object. The file name for a configuration object is equal to the unique name of the configuration, with a '.yml' extension. The default configuration files for each module are placed in the config/install directory under the top-level module directory, so look there in most Core modules for examples.

Each configuration file has a specific structure, which is expressed as a YAML-based configuration schema. The configuration schema details the structure of the configuration, its data types, and which of its values need to be translatable. Each module needs to define its configuration schema in files in the config/schema directory under the top-level module directory, so look there in most Core modules for examples. Note that data types label, text, and data_format are translatable; string is non-translatable text.

Simple configuration

The simple configuration API should be used for information that will always have exactly one copy or version. For instance, if your module has a setting that is either on or off, then this is only defined once, and it would be a Boolean-valued simple configuration setting.

The first task in using the simple configuration API is to define the configuration file structure, file name, and schema of your settings (see Configuration YAML files above). Once you have done that, you can retrieve the active configuration object that corresponds to configuration file with a call to:

$config = \Drupal::config('');

This will be an object of class \Drupal\Core\Config\Config, which has methods for getting and setting configuration information. For instance, if your YAML file structure looks like this:

enabled: '0'
  baz: 'string1'
  boo: 34

you can make calls such as:

// Get a single value.
$enabled = $config->get('enabled');
// Get an associative array.
$bar = $config->get('bar');
// Get one element of the array.
$bar_baz = $config->get('bar.baz');
// Update a value. Nesting works the same as get().
$config->set('bar.baz', 'string2');
// Nothing actually happens with set() until you call save().

Configuration entities

In contrast to the simple configuration settings described in the previous section, if your module allows users to create zero or more items (where "items" are things like content type definitions, view definitions, and the like), then you need to define a configuration entity type to store your configuration. Creating an entity type, loading entites, and querying them are outlined in the Entity API topic. Here are a few additional steps and notes specific to configuration entities:

  • For examples, look for classes that implement \Drupal\Core\Config\Entity\ConfigEntityInterface -- one good example is the \Drupal\user\Entity\Role entity type.
  • In the entity type annotation, you will need to define a 'config_prefix' string. When Drupal stores a configuration item, it will be given a name composed of your module name, your chosen config prefix, and the ID of the individual item, separated by '.'. For example, in the Role entity, the config prefix is 'role', so one configuration item might be named user.role.anonymous, with configuration file user.role.anonymous.yml.
  • You will need to define the schema for your configuration in your modulename.schema.yml file, with an entry for 'modulename.config_prefix.*'. For example, for the Role entity, the file user.schema.yml has an entry user.role.*; see Configuration YAML files above for more information.
  • Your module may also provide a few configuration items to be installed by default, by adding configuration files to the module's config/install directory; see Configuration YAML files above for more information.
  • Some configuration entities have dependencies on other configuration entities, and module developers need to consider this so that configuration can be imported, uninstalled, and synchronized in the right order. For example, a field display configuration entity would need to depend on field instance configuration, which depends on field and bundle configuration. Configuration entity classes expose dependencies by overriding the \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies() method.

See also



Namesort descending Location Description
Config drupal/core/lib/Drupal/Core/Config/Config.php Defines the default configuration object.


Namesort descending Location Description
ConfigEntityInterface drupal/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php Defines the interface common for all configuration entities.


drupal/core/modules/system/core.api.php, line 209
Documentation landing page and topics, plus core library hooks.