Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

What is a configuration collection?

A configuration storage can contain multiple sets of configuration objects in partitioned collections. The collection key name identifies the current collection used. The storage interface contains the method getCollectionNames() to list all the existing collections. This means that config sync will be able to compare incoming config in sync to active config even if the module that writes to that particular collection is not installed. So for example, if sync contains a collection called language.de, we can discover this and display to the user that this configuration will be synchronized even when the language module is being installed at the same time.

A valid collection name contains letters (A-Z or a-z), underscores or dots.

Creating a collection

A collection in the active storage can be created using the following code snippet.

  $collection = \Drupal::service('config.storage')->createCollection('language.de');
  // Write to the collection.
  $collection->write('some.configuration', $some_data);

How collections are represented in different storages

  • DatabaseStorage has a collection column in its database schema.
  • FileStorage uses sub directories. Dots have a special meaning which allows for nesting of configuration collection directories. For example 'language.de' creates a subdirectory called 'de' inside a directory called 'language'
  • Cachedstorage creates a separate bin for each collection

Config installation

Modules can make the config installer check additional collections during module install by listening to the ConfigEvents::COLLECTION_NAMES event and adding their possible collections to the list.

  /**
   * Reacts to the ConfigEvents::COLLECTION_NAMES event.
   *
   * @param \Drupal\Core\Config\ConfigCollectionNamesEvent $event
   *   The configuration collection names event.
   */
  public function addCollectionNames(ConfigCollectionNamesEvent $event) {
    $collections = array();
    foreach (\Drupal::languageManager()->getLanguages() as $language) {
      $collections[] = $this->createConfigCollectionName($language->getId());
    }
    $event->addCollectionNames($collections);
  }

  /**
   * {@inheritdoc}
   */
  static function getSubscribedEvents() {
    $events[ConfigEvents::COLLECTION_NAMES][] = array('addCollectionNames');
    return $events;
  }

Above is an example of an event subscriber adding a collection for each language enabled on a site.

If something occurs on a site that creates a new possible collection and you need to scan all enabled extensions for default configuration to install then you can do the following:

  $collection_name = 'new.collection';
  \Drupal::service('config.installer')->installCollectionDefaultConfig($this->createConfigCollectionName($collection_name));

Config synchronisation

New, updated or deleted collections are automatically included in during configuration synchronisation. There is nothing for a module that stores configuration in collections to do.

Impacts: 
Site builders, administrators, editors
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done

Comments

manarth’s picture

The examples/classes given (e.g. Drupal\Core\Config\ConfigCollectionNamesEvent) have been deprecated as part of #2224887: Language configuration overrides should have their own storage.

See more in change record Language configuration overrides now use configuration collections.