Drupal  8.2.6
API documentation
Data Structures
Configuration API

Data Structures

class  Config
class  ConfigFactory
interface  ConfigFactoryInterface
interface  ConfigEntityInterface
class  ImmutableConfig

Detailed Description

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 https://www.drupal.org/developing/api/8/configuration 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 https://www.drupal.org/node/1928898 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:

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.

Configuration schema and translation

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.

Configuration can be internationalized; see the Internationalization topic for more information. Data types label, text, and date_format in configuration schema are translatable; string is non-translatable text (the 'translatable' property on a schema data type definition indicates that it is translatable).

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 mymodule.foo.yml with a call to:

$config = \Drupal::config('mymodule.foo');

This will be an object of class , which has methods for getting 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');

The Config object that was obtained and used in the previous examples does not allow you to change configuration. If you want to change configuration, you will instead need to get the Config object by making a call to getEditable() on the config factory:

$config =\Drupal::service('config.factory')->getEditable('mymodule.foo');

Individual configuration values can be changed or added using the set() method and saved using the save() method:

// Set a scalar value.
$config->set('enabled', 1);
// Save the configuration.

Configuration values can also be unset using the clear() method, which is also chainable:

$config_data = $config->get('bar');

In this example $config_data would return an array with one key - 'baz' - because 'boo' was unset.

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 entities, and querying them are outlined in the Entity API topic. Here are a few additional steps and notes specific to configuration entities:

See also