Drupal 8 Config Management - how should I add config to a D8 site?

For me this is the biggest unanswered question hanging over my development of Drupal 8 websites:

How should I add config to a Drupal 8 site?

Before I go any further I should warn you that despite providing plenty of options, this article will not provide a definitive answer. After much investigation, thought and discussion I suspect different solutions will apply in different situations - I wish there was a silver bullet; a solution that is best for every situation, but (as yet) there isn't.

The problem

Imagine you are developing an existing Drupal 8 installation and you want to add, for example, a pre-existing view saved as a config file. How should you add that to your site? What about if you had 2 config files, or 10, or even 100 - how would you do it then?

The solutions(?)

The rest of this article will highlight some possible methods by which you could import config file(s).

/config/install directory

Config files can be added to a site as part of enabling a module by placing them in the /config/install directory of the module. This functionality is described in more depth in the drupal.org article Include default configuration in your Drupal 8 module.

If the migration of config is a one-time-only affair then this is a great option and the workflow is equally simple for any number of config files. BUT the development of a site is more often an iterative process - what happens when you need to add just one more config file? Simply adding this additional file to the /config/install directory of a currently enabled module will have no effect. In theory you could uninstall the module and then re-enable it, but this is not always an option if the module is a dependency of other modules. Besides this workflow is becoming cumbersome and is clearly not the intended functionality of the /config/install directory.

Configuration Synchronization

The apparent obvious solution to adding config would be the Configuration Synchronization user interface (Admin menu: Configuration > Development > Configuration Synchronization) and in some cases it is. The interface provides two options: import a single item of config or a full archive (for more details read Managing configuration in Drupal 8 on drupal.org).

Single item

The user interface for importing a single item of config is straightforward and ideal for that particular use case, but not if the number of config items increases. This workflow would not be suitable if there were, for example, ten or more items of config that required importing.

Full archive

Unfortunately, the alternative to "Single Item" is not "Multiple Items" it is "Full Archive" instead. In this case the workflow is as easy for one item of config as it would be for 100, but the steps can be complicated because this is not the prime intention of the functionality.

To add config via the Full Archive configuration synchronization the steps are as follows:

1. Export the complete current configuration (/admin/config/development/configuration/full/export)

2. Add your additional config file(s) - there are two options for doing this:

a. Continue in the UI by:
* Unzipping the config export
* Adding the additional config file(s)
* Zipping the new complete config
* Uploading the new complete config zip (/admin/config/development/configuration/full/import)

b. Or Use the file system instead of the UI by:
* Locating the (not zipped) export of the complete config in the sync directory (by default /sites/default/files/config/sync)
* Adding the additional config file(s)
* Running the synchronization (/admin/config/development/configuration)

Update hook

In some cases the simplest method would be to manually convert the config file(s) into code that can be run in an update hook. This workflow would be more prone to errors due to transcribing the config, but would be ideal for simple config such as a Role, e.g.

$role = Role::create([
  'id' => 1,
  'label' => 'role_example',
  'weight' => 0,
  'is_admin' => FALSE,
  'permissions' => [],
]);

Contrib modules

There are already a number of contrib modules that aim to help with configuration management. A couple worth investigating are:

• Config update
• Config sync

There are plenty of other options too and I would recommend a thorough search of drupal.org to find the best for your requirements.

Core issues

At least a couple of issues have been raised against core regarding the management of config:

• Add revert functionality to Config entities
• Detect if default configuration of a module has been changed, and allow to restore to the original

Both of these (and possible others too) are worth keeping track of.

Custom code

Another option is to write your own solution code. If you select this option, let me know how it goes!

The debate continues

That is the best I have come up with so far, but this is by no means an exhaustive list of solutions - if you have a suggestion or, even better, a single, general solution then please comment below.

My quest for a Grand Unifying Theory continues...