Drupal 8 Configuration Split

With the introduction of Drupal 8, the Drupal project introduced a bit of a paradigm shift for managing configuration for Drupal sites, moving toward encapsulating configuration separately from content and providing a mechanism to manage configuration changes more effectively through Configuration Manager, which is a Drupal Core module.

Configuration Manager provides a mechanism for importing, exporting and synchronizing a site’s configuration components, which is great when you want to maintain a consistent configuration across different development environments.

But what happens when you want to maintain configuration differences in certain environments?  An example would be configuring the Devel module for local developer environments, but disabling that module once you deploy changes to Staging or Production. Or perhaps enabling the core Database Logging module on your development server to make accessing error logging quick and easy for developers, but disabling that module on your Production site since logging messages to the database has performance implications.

Out of the box, the only way to manage differences between environments is through a manual process or a clunky tracking process to maintain separate configuration files for different environments.

Well, given that we are a development community famous for problem-solving, the Drupal Community stepped up and wrote a module for that.

Configuration Split

Configuration Split is a Drupal 8 module that provides a way to segregate configuration components so that you can isolate configuration components for different environments. This allows project developers to segregate configuration for development, specific modules or settings separately from the configuration that is set up for a staging or production environment.

In order to use Configuration Split effectively, enable the module, and start in a local development environment. Configure your site locally so that, instead of storing exported configuration files in the default location inside the sites/default/files directory, you create a directory outside the Drupal docroot to house configuration settings.

For example:

Create a config folder within your project where your Drupal project will export configuration files, and make it writable by your web user:

docroot (drupal web root)
config
   -sync (configuration export storage)

Uncomment the following lines from your settings.php file:

…
# if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
#   include $app_root . '/' . $site_path . '/settings.local.php';
# }
…

And use settings.local.php to store settings configuration for each environment.  If you’re accustomed to working with different environments anyway, you’ve probably already got a settings.local.php file that contains, among other things, database settings for your local environment.  You’ll need to create this file, and place it in the same directory as settings.php (normally sites/default/files).

Insert the following line above the uncommented lines in your main settings.php file:

…
## Disable split config settings
$config['config_split.config_split.local_dev']['status'] = FALSE;
…

Configure your site for production—disable devel, views_ui, field_ui, etc; don’t worry if you are just starting, this is a baseline configuration and you can change it later.  Export your configuration with drush cex.

Now comes the fun part.  Add a second directory inside your config directory, making sure it is writable by the web user. This directory will be used to store your development environment specific configuration:

docroot (drupal web root)
config
   -sync (configuration export storage for production)
   -local_dev (configuration export storage for local development)

In your settings.local.php file, which houses your development environment specific settings, add the following lines:

…
## Enable split config settings
$config['config_split.config_split.local_dev']['status'] = TRUE;
…

This overrides the setting that was inserted in the base settings.php file, enabling a split configuration management for your local development environment.

Now you’re ready to configure your development environment modules and settings!

Creating a Development Configuration profile

Navigate to /admin/config/development/configuration/config-split and click the “+ Add Configuration Split Settings” button.

Give your development configuration a name (for example, Local Dev) and add the location of your development configuration directory, relative to the Drupal docroot, and check the “Active” checkbox.

Page down and select the modules that are specific to your local development environment in the “Blacklist -- Modules” select box (you can use the ALT key (Windows) or Command key (OS X) to make multiple selections).

When you’ve selected the modules you wish to have enabled for local development only, page down and click "Save."

Exporting your development configuration

The Configuration Split module also creates a couple of new Drush commands:

Configuration-split-export (csex)
Configuration-split-import (csim)

These commands supplement the core commands config-export and config-import, and specifically import and export your local development configuration settings.

To export your development environment configuration, execute the following Drush command:

drush csex local_dev -y (or the machine name of your local development configuration)

The Core config-export command will now export both your production configuration settings and your development configuration settings, isolating them to the configured subdirectories within your config directory.

Managing configuration between environments

As you add and configure more modules specifically for your development environment, you can modify the configuration split profile for your local development environment, adding modules and/or configuration settings changes specific to local development, and re-export those changes via Drush.

To manage your project configuration, you can choose to include your development configuration directory in source control (to share with other developers on your team) if you like.  The configuration setting you included in your base settings.php file:

…
## Disable split config settings
$config['config_split.config_split.local_dev']['status'] = FALSE;
…

will disable the configuration split between the “sync” directory and the “local_dev” directory, and executing drush cim on your production server will ignore the configuration files in your “local_dev” directory.  

So, any continuous integration scripting process that you may have in place that imports configuration files should still work just fine for your production environment. Of course, we’d advise you test this in a development or staging server environment before implementing this in production.

Want to learn more about Drupal development?

Check out our training schedule.