Drupal's configuration system helps to solve the problem of moving changes in configuration from development to production. It does this in two ways: by providing a unified way to store configuration and by providing a process by which configuration changes can be imported and exported between instances of the same site. The configuration system is the result of work completed within the Configuration Management Initiative (CMI).
In this introduction, we'll provide:
- An overview of Drupal's configuration system
- Key concepts that you should know about
Goal
Be able to explain at a high-level the key concepts addressed in Drupal configuration management system.
Prerequisites
- None.
Watch: Introducing the Configuration System
About the configuration system in Drupal
The configuration system facilitates the storage and transfer of site configuration from one instance of a site to another, i.e. from dev to staging to live.
The configuration system enables you to define either simple configuration or configuration entities. Simple configuration can be as simple as a key/value pair or a moderately more complex array of values that include text, Boolean, or integers. Configuration entities are used to define a "type", much like a content type, and enable you to create zero or more configuration items of this type. Views, image styles, and even content types are configuration entities.
Let's continue this introduction to the configuration system by outlining several more key concepts and ideas that you'll notice repeated throughout these lessons on the configuration system in Drupal.
This tutorial benefited from configuration system co-maintainer Matthew Tift's article on lullabot.com, Configuration Management in Drupal 8: The Key Concepts (originally published November 4, 2015).
Configuration moves between instances of the same site
Drupal's configuration system is designed to facilitate the process of moving configuration between instances of the same site. Each site has a UUID (Universally Unique Identifier) in the system.site configuration item. When a site imports configuration changes, the import files must match the site's UUID. Because of this, new environments for the site should be created as clones.
To learn how to clone your Drupal site see the following related tutorials:
Not a replacement for Features
Because the contributed module Features was used so extensively in Drupal 7 to move configuration changes from dev to live, it is a common misconception that configuration management in Drupal works in similar fashion and thus now replaces the Features module. But this is not the case.
Features enables you to package configuration into modules that someone could enable or disable on another site. For example, if you had a great set of configuration for a blog that you wanted to reuse as a starting point for any client site that needs a blog, you could use Features to package configuration related to the blog. While the Features module leverages the configuration system, it is meant to be used to package configuration, not deploy configuration for a whole site.
The configuration system is not designed to package bundles of configuration for use on wholly different Drupal sites. It was meant to synchronize configuration between instances of the same site, ensuring that any configuration changes to a Drupal site could be developed and tested in one environment and imported on the live site.
One of the challenges with using the Features module in Drupal 7 is that sometimes it is difficult to capture every bit of configuration in code. With the configuration system, this is no longer an issue. However, you should still use the Features module if you want to create bundles of configuration packaged into a module that can be installed on any other version-compatible Drupal site.
Sites own configuration
Modules can (and do) add default configuration to sites. You can find this by looking in the config/install subdirectory of many modules. Once that configuration has been imported into the site's active configuration, however, it is owned by the site and not the module. This means that the module can provide default configuration which is provided to the site, but once installed, the site--not the module--owns the configuration and can make changes to it without interference from the module.
This also means that updates to a module's default configuration need to include changes to the YAML files in config/install and/or config/optional for new users of the module, but the module also must implement an update hook for existing users in order for the configuration changes to be loaded. This is because config/install is not read again after installation and configuration in config/optional may also already be active if dependencies on the site were installed.
To learn more about how a module can provide default configuration, see this tutorial:
To learn more about updating default configuration in a module, see:
- Updating Configuration in Drupal 8 (Drupal.org)
Config in code or database? Or both?
It is a common misconception that the configuration system stores all configuration in code and not in a database. While default configuration is defined by modules in code, and during export and import operations, configuration is staged in files, the active configuration storage is defined by the site, and is in the database by default. But the configuration system is flexible and configurable and switching to a file-based storage, MongoDB, Redis, or other key/value store are all technically possible.
Configuration override system
The configuration override system enables you to override sensitive data in settings.php on specific environments that you don't want stored in the database. Drupal 7's $conf global variable was renamed to $config and is accessible to the configuration system by default.
Note, however, that configuration forms will display values from the site's active configuration (which may be the default, the database) and not values from $config in settings.php.
A note about workflows
While there are some sensible and usable defaults in place for the configuration system, site administrators, developers, and teams are encouraged to utilize a workflow that best suits their particular situation. For some small sites, the administrator might not ever use the configuration manager module to import and export configuration. Some teams will only use command-line tools to manage configuration and never use the UI provided by the Configuration Manager module. It's even possible to disable the configuration settings forms using the contributed module Configuration Read-Only Mode which can be desirable in cases where you want to limit configuration management to developers using Drush with files managed in a version control system like Git.
While the tutorials in our series on configuration management demonstrated a couple possible workflows, there are certainly other workflows possible. As you get more and more familiar with the configuration system, you will be able to better utilize its flexibility and be able to configure it to fit your site's needs. Drupal Planet is one possible resource for keeping tabs on Drupal developer blogs, where (among many other topics) you'll find different ideas and tools that leverage the flexibility and configurability of Drupal's configuration system.
To learn more about configuration sync and managing configuration between environments, see the following tutorials:
- Configuration Sync Directory Setup
- Synchronize Configuration with the UI
- Inspect Configuration with Drush
Recap
In this high-level overview, we learned that the configuration system facilitates the storage and transfer of site configuration from one instance of a site to another, i.e. from dev to staging to live. It is not a replacement for the Features module wherein configuration is bundled into a module and can be installed on multiple sites. Rather, the configuration system facilitates the deployment of configuration from one instance (or clone) of a Drupal site to another instance. Once configuration from an installed module is imported into a site's active configuration, the configuration is owned by the site, not the module. The active configuration is stored in the database by default but is exported and deployed via YAML files in a config sync directory. Configuration may be overridden on a particular environment through the $config array in a *.settings.php file. Finally, workflows can differ depending on a site or a team's preferences or makeup. Make a plan for how you or your team will use--or not use--the configuration system by first becoming more familiar with the system and the available tools.
Further your understanding
- What does the configuration system enable you to do? What is it not meant to do?
- What is an instance of a Drupal site? If you've worked on a Drupal project, what did your team name the different instances of that site?
- For Drupal 7 users, how did you deploy configuration from development to production? At a high level, how do you see the configuration system changing your process for a Drupal project?
Additional resources
- Configuration Management in Drupal 8: The Key Concepts by Matthew Tift (Lullabot.com)