Config ignore module tutorial for Drupal

In the previous tutorial, we spoke about the Config Split module for Drupal 8. Today I'm gonna show you another configuration-related module for Drupal 8/9 – Config Ignore. They are partially overlapping with each other. Both of them help us keep configurations among different environments separate. However, the usage is slightly different. So is the result. The best way to learn and understand it is by using real-life examples.

Let's say we need to make some development related to the sending mail functionality. We may want to style a template. Or make an event subscriber where we want to send a specific mail to the site admin. Or make some notification on a cron execution. Or just make sure we can send emails at all!

Let's use the site's default email for this example. So in the local environment, we would most likely use our own email, right? But when we export the configurations for the testing or the live environment, we don't want our email to be set as the default one, but instead, we'd want this to be the real email. So, we need to ignore this configuration. Can we do that?

Sure we can! Curious already? Let's get started!

We need to first install and enable the Config Ignore module:

composer require drupal/config_ignore
drush en config_ignore
 

Let's also clear the cache

drush cache:rebuild

and we'd have the module up and running already. It has a dependency on another module – Config Filter, but it is handled automatically for us. We just have to approve enabling both modules if needed. This module works closer to the core's configuration system, so it is not so obvious by first sight where it takes place. We don't have any new entries in the main Configuration → Development area. Let's see what do we have there.

As mentioned already – nothing special. Just the default configuration synchronisation system, provided by the core which we usually use to import and export our configurations. When we execute these actions via the drush commands [config:import] and [config:export], we basically trigger the same actions we would see here. But let's see what's inside.

OK, now here we already have another tab beside the standard ones. This is the ‘Ignore’ tab where we need to work. Let's see what it looks like.

It's pretty simple. Just a form where we could place our configurations which we want to be ignored. The people who created it even describe how to use it. Thanks, guys! I won't duplicate the examples we have there, but instead, focus on our specific use case. We need our email to be only used for local development. The next things we'd need are:

• when we export the configurations, our email should not be exported among them
• when we import the configurations, we don't want the real email from the testing or the live environment for our development purposes, so we don't want our configuration overwritten.

Config Ignore to the rescue! We have few ways of describing the configurations. But first, let's export the initial configurations in order to be able to see the difference later on:

drush config:export

Note: Please, do not perform the following step yet. I am doing it here only for explanation reasons.

I went into the Configuration → System → Basic site settings, changed the email there with my own one, and saved it. Now when we go back to the configuration synchronisation part (Configuration → Development → Configuration Synchronisation), we see a change in the system.site.yml file and we may check it by pressing View differences.

Let's now add the configuration string from the image below in the ‘Ignore’ tab and press the ‘Save configuration’ button.

But now, when we export again, we'd see both changes – the one in system.site and the other in the config_ignore.settings. And we don't want that. We need just the second one. The reason we see them both now is that the config system doesn't know yet it has to ignore the system.site one. So what would be better to do is to first add the record in the Ignore area, export, then change the email and save. OK, then let's do it right this time.

We visit the Ignore tab and add one of the following:

- system.site → Note this would ignore the entire ‘Basic site settings’ page.

- system.site:mail → This would only ignore the email part of the setting. Noticed the colon before the mail? This is how we set only a specific key from a configuration file to be ignored. Let's go with this one now. This time, we should have the following:

We are ready to export via:

drush config:export

so we make sure that the email will be ignored next time we change it. This time we only see the change in ‘config_ignore.settings’. This is what we expect. Let's now go and change that email already. After that, let's see what does the ‘Synchronise’ tab show us.

The system is smart enough to see the difference, but ignore it and even let us know it has been ignored already. Now we only see there is a change, but we don't have the button to view it. We are now ready to change that email value as much as we like. It is important to say that since we only ignored the mail, any other change in the system.site would be handled as a real change by the system, i.e. it wouldn't be ignored unless we put the entire system.site in the Ignore area or any other of its keys in the same way we did with the mail. Every new record should be placed on a new line. This is how the Config Ignore module works.

I'm sure you already noticed this, but let me point it out only for completeness reasons. This configuration should be now set up with its real value on every different environment, meaning that you would still need to update the mails in the testing, live, or any other environments. It won't be replaced with either importing or exporting actions.

That would work with every configuration, even if it's a custom one we defined ourselves. Just keep in mind that ignoring a new configuration would leave it empty, even if it has a value on the local environment. Exporting it however would generate the yml file so it would be available everywhere.

This is a brief tutorial for the Config Ignore module usage. We might also point out some differences between it and the Config Split module. They both have their strengths. So how do we choose which one to use? Well, this depends on the use case we have, but let's see their specifications:

• Config Ignore – simpler to use, closer to the core functionality. Adding another configuration for ignoring is as simple as just putting it into the form. However one needs to take care of the same configuration in each environment. If there are just a few records added, this is not a real issue though.
• Config Split – more powerful, provides the option to define all possible environments in advance. It allows us to predefine the configurations we want per each environment and forget about them once imported. There is also an option to configure an entire module being enabled or disabled per environment much easier. However, it is slightly more difficult to set up and use.

At the end of the day, it's really a matter of preference.

I hope you find this tutorial useful!