Configuration Storage
This documentation needs review. See "Help improve this page" in the sidebar.
By default, configuration information in Drupal 8 and later is stored in the database.
Configuration File Format (YAML)
Extensions (modules, themes, and profiles) provide configuration data in YAML files.
Here is an example of a configuration file:
some_string: 'Woo kittens!'
some_int: 42
some_bool: true
Configuration can also be nested. Here is an example:
name: thumbnail
label: 'Thumbnail (100x100)'
effects:
1cfec298-8620-4749-b100-ccb6c4500779:
id: image_scale
data:
width: 100
height: 100
upscale: true
weight: 0
uuid: 1cfec298-8620-4749-b100-ccb6c4500779
Configuration Schema
Configuration has a schema. This is described in the Configuration schema/metadata documentation.
Default Configuration for an extension
An extension (module, theme, or profile) that provides default values for its configuration must put that configuration into YAML files in its config/install
sub-directory.
If the extension only needs basic Simple Configuration settings, all of the default configuration could go into one modulename.settings.yml file. For more complex settings, you can separate your configuration into multiple files. Configuration Entities must each be put into their own YAML files, and they should be generated by having the module write out its configuration (don't try writing them by hand).
To provide default values for config that requires a dynamic value (which cannot, therefore, be set in modulename.settings.yml) do so in hook_install(). E.g:
/**
* Implements hook_install().
*/
function modulename_install() {
// Set default values for config which require dynamic values.
\Drupal::configFactory()->getEditable('modulename.settings')
->set('default_from_address', \Drupal::config('system.site')->get('mail'))
->save();
}
Optional Configuration for an Extension
Optional configuration items for an extension (module or theme) are stored in the config/optional
sub-directory.
These are configuration items that depend on something that the extension itself does not explicitly depend on, so they are only installed if all their dependencies are met.
For example, in the scenario that module A has optional configuration which requires module B, but module A is installed first and module B some time later, then module A's config/optional
directory will be scanned at that time for newly met dependencies, and the configuration will be installed then. If module B is never installed, the optional configuration item will not be installed either.
Active configuration storage
By default, Drupal 8 stores the active configuration in the database for better performance and scalability. See Default active config changed from file storage to DB storage for more information.
Update configuration from yaml to the database
If during development you need to update configuration from yaml to the database, you can use the drush config-import (cim ) command.
You edit the config yml file in the active config folder (as defined in settings.php e.g sites/default/files/config_6dh1U_2YKLGrrh5oLxAgobbledygook/sync) and then run drush cim. Clear the caches (drush cr) to see the changes.
When you are satisfied with the settings in the yml file you copy them to your module or theme.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion