Environment and configuration split in Drupal 8

Following article describes idea on how we can use config_split module to differentiate configuration between two common project environments: development and production. This article will address development named as local. The reason being is that Drupal comes with the existing settings file called settings.local.php. But this is its just an idea, change the whole naming as you like.

Environment variable

First we need to modify default settings.php file to switch the appropriate settings override file based on the environment site is running. For this reason we are checking if environment variable SITE_ENV is present, otherwise we use local (development) settings.

/**
 * Enable site environment variable.
 *
 * Used to load configuration override depending on the environment.
 * Setting SITE_ENV='production' will load settings.production.php.
 */
if (!($settings['environment'] = getenv('SITE_ENV'))) {
  $settings['environment'] = 'local';
}

if (file_exists($app_root . '/' . $site_path . '/settings.' . $settings['environment'] . '.php')) {
  include $app_root . '/' . $site_path . '/settings.' . $settings['environment'] . '.php';
}

Switching between environments 
For HTTP requests coming to the server, environment variable can be set in the Apache's vhost configuration file or /etc/apache2/apache2.conf file (don't forget to reload|restart Apache).

SetEnv SITE_ENV production

When using this approach, you will also have to set the shell environment variable for your CLI scripts such as drush by adding it to the ~/.profilefile or setting it directly:

$ export SITE_ENV="production"

Another option is to use system wide environment variable by adding it to the /etc/environment.

Configuration split with config_split module

To prepare for configuration split we create following two folders:

• config/split/local
• config/split/production

Configuration folders explained 

• sync (config/sync) - Default configuration common to all environments.
• local (config/split/local) - Development configuration used for development.
• production (config/split/production) - Configuration used in production.

How to do a configuration split - workflow

For simplicity I will only demonstrate the split for devel module (which should not be enabled when in production).

Clean start 
If your current website does not have devel module enabled yet, follow this steps:

1. Enable devel module
2. Configure local split to split devel module:  

   admin/config/development/configuration/config-split.

3. Set local config split as active
4. Run the split drush config-split:export local

Modules already enabled
When you are working on a site which already has everything setup, and you want to enable config_split and exported in the sync folder, process of setting things up involves disabling of modules, exporting configuration and than do configuration split.

To split already enabled devel module, following steps should be made:

1. Disable devel module.
2. Configure local split to split devel module:  

   admin/config/development/configuration/config-split.

3. Export configuration drush cex (NOTE: make sure no config split is enabled at this point).
4. Set local config split as active.
5. Enable devel module.
6. Run the split drush config-split:export local

To verify things, at step 6 configuration should be exported to config/split/local folder.

NOTE: When config split is active and we are runing drush config:import first import, nothing will change since config_split.config_split.[environment-name].yml needs to be imported. Configuration split import will take effect when runing drush config:import for the second time.

Enabling configuration split based on the environment 

Last step that is left is to modify settings.php to dynamically enable config split based on the SITE_ENV environment variable.

if (file_exists($app_root . '/' . $site_path . '/settings.' . $settings['environment'] . '.php')) {
  include $app_root . '/' . $site_path . '/settings.' . $settings['environment'] . '.php';
  $config['config_split.config_split.' . $settings['environment']]['status'] = TRUE;
}