Simple Configuration API
This page describes the API for getting and setting configuration data, for Simple Configuration. (This is not for information stored in Configuration Entities.)
Each module can provide default configuration. For example, the maintenance mode settings are defined in
core/modules/system/config/install/system.maintenance.yml. In this file, the first part is a namespace representing which module supplied this configuration (system module in this example), which is followed by the sub-system (maintenance in this example). The file must be under a config/install directory. This file contains the following YAML:
message: '@site is currently under maintenance. We should be back shortly. Thank you for your patience.' langcode: en
Configuration can also be nested, as in the performance settings (
cache: page: enabled: '0' max_age: '0' preprocess: css: '0' js: '0' response: gzip: '0'
IMPORTANT: The root keys must be a mapping
The data at the root of a configuration must be represented as a mapping and not an unpredictable sequence. For example, if you are storing data for each available entity type, make the parent key the entity type and add a root key of
entity_type. See the example layout below:
entity_type: commerce_order: foo: 'bar' node: foo: 'bar' user: foo: 'bar'
If the entity types are the root key then it is impossible to represent the configuration using schema. Additionally Drupal core would be unable to add extra information when the configuration is installed as part of a module (or theme) installation.
Interacting with configuration
You interact with these files through the Config object, and you instantiate a Config object by calling the function
config() with the filename minus the extension. Calling the config function will return an instance of \Drupal\Core\Config\ImmutableConfig.
//Immutable Config (Read Only) $config = \Drupal::config('system.performance');
//Mutable Config (Read / Write) $config = \Drupal::service('config.factory')->getEditable('system.performance');
Once you have a Config object, you can interact with it in various ways.
Configuration is read using the
get() method. This can be used in several ways. To read a piece of configuration, just provide its key.
$config = \Drupal::config('system.maintenance'); $message = $config->get('message');
\Drupal::config() can also be chained.
$message = \Drupal::config('system.maintenance')->get('message');
To read nested configuration, separate the keys with the '.' character.
$enabled = \Drupal::config('system.performance')->get('cache.page.enabled');
You can read configuration at any level, if there is configuration nested underneath your level, it will be returned as an array.
$page_cache = \Drupal::config('system.performance')->get('cache.page');
This would return an array with two keys - 'enabled' and 'max_age'.
To return all the data in a config object, just call
get() with no arguments.
To change a configuration you will need to get an instance of \Drupal\Core\Config\Config (Mutable config object) by making a call to getEditable() on the config factory. Attempting to make a change or calling a delete() / save() function on an instance of \Drupal\Core\Config\ImmutableConfig will throw a ImmutableConfigException.
This is done in the following way:
Configuration is changed or added using the
set() method and saved using the
save() method. Note that configuration must be explicitly saved; simply setting data into a configuration does not save it.
You save data into a config object the same way that you read it, by referencing the keys and saving appropriate data. The syntax is the same as
variable_set() was in previous versions of Drupal.
$config = \Drupal::service('config.factory')->getEditable('system.performance'); // Set a scalar value. $config->set('cache.page.enabled', 1); // Set an array of values. $page_cache_data = array('enabled' => 1, 'max_age' => 5); $config->set('cache.page', $page_cache_data); // Save your data to the file system. $config->save();
set() function is also chainable, so if you only need to change one value, you can do it in a single line of code.
If you want to replace all the data in the configuration object, use the
setData() function. You cannot use
setData() to replace just a subset of the data - if you want to replace anything less than the entire object you must use one or more calls to
set() instead. When using
setData() you must specify every key and value in the same associative array format as is returned by
get() with no arguments. For the system performance settings in
system.performance.yml, this would look like the following:
// Set all values. \Drupal::service('config.factory')->getEditable('system.performance')->setData(array( 'cache' => array( 'page' => array( 'enabled' => '0', 'max_age' => '0', ), ), 'preprocess' => array( 'css' => '0', 'js' => '0', ), 'response' => array( 'gzip' => '0', ), )) ->save();
Individual configuration values can be unset using the
clear() function, which is also chainable.
$config = \Drupal::service('config.factory')->getEditable('system.performance'); $config->clear('cache.page.max_age')->save(); $page_cache_data = $config->get('cache.page');
In this example
$page_cache_data would return an array with one key - 'enabled' - because 'max_age' was unset.
Whole configuration sets can be removed using the
Note that this should not be followed by a call to
save(), as doing so would create an empty version of the configuration set.
Avoid instantiating config objects multiple times within the same function, as this is a performance drain. The following code unnecessarily instantiates the config object 'foo.bar' twice.
\Drupal::service('config.factory')->getEditable('foo.bar')->set('foo', 'foo')->save(); \Drupal::service('config.factory')->getEditable('foo.bar')->set('bar', 'bar')->save();
A better solution would be to instantiate the config object once, save it into a variable, and work with that variable for the rest of your code scope.
$config = \Drupal::service('config.factory')->getEditable('foo.bar'); $config ->set('foo', 'foo') ->set('bar', 'bar') ->save();