My Drupal 8 Learning Path: Configuration Management in D8

Recently, fellow Acquian Tanay Sai published a blog with a link to the activity cards he and other members of the Acquia India team have been following to learn Drupal 8.

Each card is a self contained lesson on a single topic related to Drupal 8: with a set objective, steps to complete the learning exercise, links to blogs, documentation, and videos to get more information.

As part of my own D8 learning path, I've begun working through these activities and will be blogging about what I found as I work through them. This particular post will cover the activity titled, "Day 01 - Configuration Management in D8." For ease of use, I'm including a screenshot of the lesson below, but if you'd like to play along at home, I encourage you to check out Tanay's blog post for a link to the Google Doc where the activities are defined.


The first thing I did was head over to the Acquia Cloud Free site I keep as a sandbox in the cloud. I set it to install the latest D8 core (8.1.0, at this time). While that was working, I pulled down a fresh copy of DrupalVM and started spinning up a local environment, with the plan to configure it to mirror the cloud site.

The cloud site finished provisioning first, so I did some initial configuration there (like turning off allowing Anonymous users to create accounts) while DrupalVM was setting up my local.

Right away I noticed an error on the status report page saying ../config/default wasn't writable. It told me to check the file system settings page. This took a bit of head scratching since I know D8 uses a directory in sites/default/files to store config and wasn't sure where the directory was coming from in the first place, but I finally tracked it down.


Acquia uses an account-specific settings file to force settings like database connection strings, memcache bins, and other items into your settings.php file. That file for D8 also includes a setting to change the config directory from a location inside the file path to a config directory above the docroot. This has the advantage of allowing your config to be in version control (since sites/default/files is generally ignored by git). But as an undocumented feature, it was a bit baffling. Further discussion revealed there's an issue in the core issue queue, questioning if the config directory not being writable should even be a check (though if it isn't you won't be able to use the UI to do full config imports).

As an aside, if you don't want this behavior on the Acquia environment, just add a line to your settings.php file *below* the Acquia include file lines and you can set the config directory to be whatever you want.

Once DrupalVM finished setting up my local environment and I got the local and remote environments to accept that they were the same site, the lesson activities went smoothly. But when I finished them I found myself wondering three what ifs…

What happens if I …..

1. Delete everything from the sync directory?

Not a thing. The config sync UI page just says there's nothing to sync.

2. Put only one file in the sync directory?

This seems like a semi-reasonable use-case, right? If I want to update the site name, I should be able to just push up the with the new site name setting. But when doing that, I got a WSOD at /admin/config/development/configuration and a PHP fatal reading

"Recoverable fatal error: Argument 1 passed to Drupal\field\ConfigImporterFieldPurger::getFieldStoragesToPurge() must be of the type array, boolean given, called in /var/www/d8sandbox/docroot/core/modules/field/field.module on line 333 and defined in Drupal\field\ConfigImporterFieldPurger::getFieldStoragesToPurge() (line 111 of /var/www/d8sandbox/docroot/core/modules/field/src/ConfigImporterFieldPurger.php)."

It took a bit of mucking about to nail this down, but it turns out that if there are any files in the sync directory and core.extension.yml is not one of them, you'll get that fatal. Given the error, it kind of makes sense, but seems like core should handle it with a bit more grace than a WSOD.

It also turns out that there's another file with semi-magical powers here. The other is, which contains the uuid key. Without this file in the sync directory, you'll just get a message saying, "The staged configuration cannot be imported, because it originates from a different site than this site. You can only synchronize configuration between cloned instances of this site."

Worth noting that putting only single files into the sync directory is not the expected use case; most likely if you're doing things that way you're going to get into trouble.

3. Manually edit the core.extensions.yml to add/remove modules?

As you'd expect, adding modules that exist in the code base to the core.extensions.yml file installs them; removing modules from the file uninstalls them. I had kind of expected things would WSOD if I added a module that isn't in the code base to the extensions file, but it handled it pretty well when running drush config-import, simply reporting an error that it couldn't install the non-existent module.

Drupal\Core\Config\ConfigImporterException: There were errors validating the config synchronization. in Drupal\Core\Config\ConfigImporter->validate() (line 725 of     	[error]
The import failed due for the following reasons:  [error]
Unable to install the shaboopie module since it does not exist.

Alright, that's enough or this lesson.

Activity 2 in Tanay's list is the Paragraphs module, which seems to be the new rage. But the activity is really configuration-focused and non-core, so I'm going to skip it and go on to "Lesson 3: Building Configuration Forms."

I'm looking forward to my next D8 lesson. I'll post my learning experience afterwards.