Configuration Import Export Transformation

Customizing the exported and imported configuration in the synchronization storage is a powerful feature that allows you to tailor your Drupal site's setup to specific needs. This flexibility is particularly useful for excluding development modules' configuration or adapting environments for different versions of your site. In this section, we'll explore how you can achieve this through configuration import and export transformations.

Exclude Module configuration

Within core you can now exclude configuration provided by a module from being imported or exported. This is often done by using config split, see contrib modules below. However it can also be done simply using core since version 8.8 if the environment configuration does not need to be separated.

To use this in settings.php configure:

$settings['config_exclude_modules'] = ['devel', 'stage_file_proxy'];

You need to use the drupal UI or drush 10+ for this to work.

Contrib modules

Most common use cases for altering configuration can be done using modules in contrib. The most used Config split allows you to split off certain configuration from the sync directory into separate directories. When importing and exporting it is then possible to have the split folder merged with the main sync directory or leave them out. There is extensive documentation about how to use Configuration Split.

Others include ignore, delete, partial export etc.

Config Import/Export transform event

Should contrib not cover your requirements, or not be an option, modules can since version 8.8 implement an event to transform configuration as they wish on import or export. The event allows you to access the active and sync configuration and the configuration being transformed by the import/export operation. This allows for altering, or copying configuration as desired to maintain or change each storage.

Generic example of an subscriber implementing the event:

use Drupal\Core\Config\ConfigEvents;
use Drupal\Core\Config\StorageTransformEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class EventSubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents() {
    $events[ConfigEvents::STORAGE_TRANSFORM_IMPORT][] = ['onImportTransform'];
    $events[ConfigEvents::STORAGE_TRANSFORM_EXPORT][] = ['onExportTransform'];
    return $events;
  }
  /**
   * The storage is transformed for importing.
   *
   * @param \Drupal\Core\Config\StorageTransformEvent $event
   *   The config storage transform event.
   */
  public function onImportTransform(StorageTransformEvent $event) {
    /** @var \Drupal\Core\Config\StorageInterface $storage */
    $storage = $event->getStorage();
    $site = $storage->read('system.site');
    // Only change something if the sync storage has data.
    if (!empty($site)) {
      $site['name'] = 'Enforced site name';
      // Write to the storage from the event to alter it.
      $storage->write('system.site', $site);
    }
  }

  /**
   * The storage is transformed for exporting.
   *
   * @param \Drupal\Core\Config\StorageTransformEvent $event
   *   The config storage transform event.
   */
  public function onExportTransform(StorageTransformEvent $event) {
    /** @var \Drupal\Core\Config\StorageInterface $storage */
    $storage = $event->getStorage();
    $site = $storage->read('system.site');
    // Prevent the slogan from being exported.
    $site['slogan'] = '';
    // Write to the storage from the event to alter it.
    $storage->write('system.site', $site);
  }
}

For a more full example this example module excludes webform configuration from export unless a value is setting in settings.php, and won't remove configuration from the database if it doesn't exist in the sync directory.