In part 2 of this three-part series, we showed you how to set up you config management flow. In this part we’ll be looking at some use cases and common issues related to config management.
Starting on a new issue, or finishing one
There is an important must-do before you start developing on a new issue, after you’ve pulled the latest code with Git. Don’t forget to always do an import of the configuration first! It should become second nature to do a “drush config-import -y” or shorthand “drush cim -y” just after a Git pull or checkout.
When you finish one, you should do a “drush config-export -y” or shorthand “drush cex -y” and check the exported files before committing your changes.
Live-specific configuration
To set live-specific configuration, you have two options:
- Set the config using the settings.php file directly on that environment
- Make split that is active on that environment
The general rule is to export your configuration in the sync folder and override for the environment that differs.
The following example should make this a bit clearer. Imagine you have an API that you need to connect to. Your local, development and staging environment should all connect to the development version of the API, while the live environment should connect to the live API.
If you have a lot of configuration to do for your API connection, you can choose to use config split to solve your problem. We can state that most environments need to connect to the development API; therefore this config should be stored in the sync folder, so it gets imported onto all environments. We then need to override that config for the live environment by using a config split that is only active on the production environment.
In practice, you would go about it in the following way:
- Make sure you have set up your environment settings files as described above
- Configure the dev settings in the configuration form
- Use “drush cex” to export all updated configuration
- Check Git if your changes have been added to the sync folder
- Go back to the config form and configure the live settings as if you were on a live site
- Use “drush csex live” to export your updated configuration only to your live split folder based on the live split settings.
- Check git if your changes have been added to the live sync folder
- Commit all your changes
- Use “drush cim” to import all the config again according to your currently active splits
Important: Make sure your drush version is higher than 8.1.10 or it won’t pickup the splits if you use drush cex or drush cim. Be aware that you still need to use csex and csim if you want to export or import from specific splits.
When you are adding configuration that should be ignored or split
If you are just creating new functionality and some of the configuration should be ignored or split. Beware that on the first import you do on other environments the config that should have been ignored or split won’t be.
This is because the newly added config to the Config Ignore or Config split module has not been taken into account yet. Sometimes, this can be to your advantage - but more often, the contrary is true.
The way to get around this, is to manually add the “Config Ignore” or “Config Split” config to the environments where you want to deploy or take a two-step approach at deployment.
Avoid changing your default language
Changing your default language after you’ve already been exporting and importing your config can result in some very strange side effects with translations.
If you ever find yourself in the situation, a good fix is to manually change the langcode in the yml files in your sync folder to your default language again. Also make sure that the strings you’ve used are in the same language as defined by the langcode.
A good rule to bear in mind: Make sure all your config exports are done in the same language. This sometimes leads to errors, because it uses the language defined by the language negotiation plugins. If you only use Drush to import and export your config, this module can help enforcing a specific language. It will force all your Drush commands to be done in a language you define. The Dropsolid dev team be working together with Bart (Xano on Drupal.org) to see if we can help him get the module to a stable release.
Config translations can be tricky
You can easily translate your configuration using the Config Translation module from core. This sometimes can lead to unexpected side effects if you consider translations to be in the grey zone between config and content.
The issue here is that config translation and interface translation sometimes overlap - take for example the name of your content type. It is stored not only in config translation, but also in string translation.
When you do an import, it will by default overwrite the translation you’ve set in interface translation. This is because the locale module has a subscriber that imports those strings on the import event. (See this issue.)
Be aware that this can even happen to custom translated strings that you use in your own code. If there happens to be a same string that is used in config, it will get overridden. In this case you can always assign a context to your translated string so it doesn’t get overridden.
For those cases where you can’t set a context on the translated string, we’ve developed and contributed the Locale: Config import module. This module will let you change the behaviour of how the translated config gets imported.
The module shows the following options:
Agreeing on best practices for those grey areas for content
As a team of developers, you should agree in advance on a couple of best practices concerning content grey areas. Below I’ve listed a few rules that we’ve been playing with at Dropsolid:
- If you create a custom block plugin, use translatable markup with context for titles.
- Initially, treat Roles and permissions as config, until you go live. Next, configure the Config Ignore module to ignore them and update them through update hooks.
- Always treat webforms as if they are content. Deploy changes through update hooks
Working towards a better flow
I hope this three-part post has provided you with some valuable insight!
This article has been a true team effort, so thanks to everyone who contributed (most notably Brent, Marek, Laurens, Kevin, Thomas and Nick). Together, we can make configuration management a little bit clearer for everyone who uses it!
No doubt this article will be changing through the coming months as everyone - including the team here at Dropsolid - is still looking to find that perfect workflow.