Configuration management in Drupal 8 provides a solution to a common problem when working with a website across multiple environments. No matter what the workflow pattern is, at some point the configuration needs to move from one place to another, such as from production to a local environment. When pushing the development work to production, you need to have some way to put the configuration in place.
Drupal 8's user interface provides a way to import and export configuration entities via the YAML format. In this recipe, we will create a content type, export its configuration, and then import it into another Drupal site.
In this recipe, we will export a single configuration entity from a development site. The configuration YAML export will be imported into the production site in order to update its configuration.
You will need a base Drupal site to act as the development site. Another Drupal site, which is a clone of the development site, must be available to act as the production Drupal site.
- To get started, create a new content type on the development site. Name the content type Staff Page and click on Save and manage fields to save the content type. We will not be adding any additional fields.
- Once the content type has been saved, visit Extend and install the Configuration Manager module if it is not installed:
- From your Drupal site's Configuration page, go to Configuration synchronization under the Development group. This section allows you to import and export configuration:
- Click on the Export tab at the top of the page. The default page will be for a Full archive export, which contains the configuration of your entire Drupal site. Click on the Single item subtab to export a single configuration entity instead:
- Select Content type from the Configuration type drop-down menu. Then, choose your content type from the Configuration name drop-down menu. Its configuration will populate the configuration textbox:
- Copy the YAML content from the textbox so that you can import it into your other Drupal site.
- On your production Drupal site, install the Configuration management module just as you did for the development site, if it is not yet installed.
- Visit the Configuration synchronization page and click on the Import tab.
- Click on Single item and select Content type from the Configuration type:
- Paste your exported configuration YAML into the textbox and click on Import:
- Click on Confirm on the confirmation form to finalize your import to the production Drupal site for your custom content type.
- Visit the Structure page and then the Content Types page to verify that your content type has been imported.
At the most basic level, configurations are just a mapping of keys and values, which can be represented as a PHP array and translated into YAML format.
Configuration management uses schema definitions for configuration entities. The schema definition provides a configuration namespace and the available keys and data types. The schema definition provides a typed data definition for each option that allows validation of the individual values and configuration as a whole.
The export process reads the configuration data and translates it into YAML format. The configuration manager then receives the configuration in the form of YAML and converts it back to a PHP array. The data is then updated in the database.
When importing the configuration, Drupal checks the value of the configuration YAML's uuid key, if present, against any current configuration with the same
Universally Unique Identifier (UUID). A UUID is a pattern used in software to provide a method of identifying an object across different environments. This allows Drupal to correlate a piece of data from its UUID since the database identifier can differ across environments. If the configuration item has a matching machine name but a mismatching UUID, an error will be thrown.
Configuration entities define dependencies when they are exported. The dependency definitions ensure that the configuration entity's schema is available and other module functionality.
When you review the configuration export for field.storage.node.body.yml, it defines node and text as dependencies:
dependencies:
module:
- node
- textIf the node or text module is not enabled, the import will fail and throw an error.
Chapter 6, Creating Forms with the Form API, the providing configuration on install or update, discusses how to use a module to provide configurations on the module's installation. Instead of manually writing configuration YAML files for installation, the Configuration management module can be used to export configurations and save them in your module's config/install directory.
Any item exported through the user interface can be used. The only requirement is that you need to remove the uuid key, as it denotes the site's UUID value and invalidates the configuration when it makes an attempt at installation.
The configuration management system in Drupal 8 utilizes the configuration schema to describe configurations that can exist. Why is this important? It allows Drupal to properly implement typed data on stored configuration values and validate them, providing a standardized way of handling configurations for translation and configuration items.
When a module uses the configuration system to store data, it needs to provide a schema for each configuration definition it wishes to store. The schema definition is used to validate and provide typed data definitions for its values.
The following code defines the configuration schema for the navbar_awesome module, which holds two different Boolean configuration values:
navbar_awesome.toolbar:
type: config_object
label: 'Navbar Awesome toolbar settings'
mapping:
cdn:
type: boolean
label: 'Use the FontAwesome CDN library'
roboto:
type: boolean
label: 'Include Roboto from Google Fonts CDN'This defines the navbar_awesome.toolbar configuration namespace; it belongs to the navbar_awesome module and has the toolbar configuration. We then need to have two cdn and roboto subvalues that represent typed data values. A configuration YAML for this schema would be named navbar_awesome.toolbar.yml after the namespace, and it contains the following code:
cdn: true roboto: true
In turn, this is what the values will look like when represented as a PHP array:
[
'navbar_awesome' => [
'cdn' => TRUE,
'roboto' => TRUE,
]
]The configuration factory classes then provide an object-based wrapper around these configuration definitions and provide validation of their values against the schema. For instance, if you try to save the cdn value as a string, a validation exception will be thrown.
- Chapter 4, Extending Drupal
configuration schema/metadatain the Drupal.org community handbook at https://www.drupal.org/node/1905070