Configuration Storage in Drupal 8

Last updated on
14 January 2017

By default, configuration information in Drupal 8 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.