Last updated February 1, 2013. Created by heyrocker on October 11, 2012.
Edited by Gábor Hojtsy, dakala, alanburke. Log in to edit this page.
Configuration Data
Each set of configuration is defined by a file on the file system. For example, the maintenance mode settings are stored in the file system.maintenance.yml. In this file name, the first part is a namespace representing which module supplied this configuration (system module in this example.) This file contains the following YAML:
enabled: '0'
message: @site is currently under maintenance. We should be back shortly. Thank you for your patience.Configuration can also be nested, as in the performance settings (system.performance.yml):
cache:
page:
enabled: '0'
max_age: '0'
preprocess:
css: '0'
js: '0'
response:
gzip: '0'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.
$config = config('system.performance');Once you have a Config object, you can interact it in various ways.
Reading configuration
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 = config('system.maintenance');
$enabled = $config->get('enabled');This code would set $enabled as the string '0'. Note that all configuration is returned as strings, any casting will have to be done on the caller's side.
Calls to config() can also be chained.
$enabled = config('system.maintenance')->get('enabled');To read nested configuration, separate the keys with the '.' character.
$enabled = 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 = 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.
Writing configuration
Configuration is changed or added using the set() method and saved using the save() method. Note that configuration must be explicitly saved, 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 = config('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();The set() function is also chainable, so if you only need to change one value, you can do it in a single line of code.
config('system.performance')->set('cache.page.enabled', 1)->save();If you want to replace all the data in the configuration object, use the setData() function, which works exactly like set() does.
Removing configuration
Individual configuration values can be unset using the clear() function, which is also chainable.
$config = config('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.
Best Practices
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.
config('foo.bar')->set('foo', 'foo')->save();
config('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 = config('foo.bar');
$config->set('foo', 'foo');
$config->set('bar', 'bar');
$config->save();