This project is not covered by Drupal’s security advisory policy.

Configuration Share enables commonly needed configuration items to be shared among multiple features and distributions.

Aim and main use case

Configuration Share is built with the aim of making it easy to build interoperable Drupal configuration modules and distributions.

How Configuration Share works

Configuration Share allows commonly needed configuration items like user roles and field storages to be designated as shared, by placing them in a module's config/shared directory. Shared configuration is not installed when a module providing it is installed. Instead, it is installed only on demand--when another piece of configuration that requires it is installed.

Thus, multiple features can share the same required configuration items without creating conflicting dependencies.

Typically, Drupal distributions put commonly needed configuration items in a "core" or "base" feature or module that becomes a dependency for most or all other features in that distribution. This means that features from one distribution cannot be used on the same site as features from another distribution, as their dependencies will conflict.

Configuration Share addresses this problem by making it possible to provide a curated set of commonly needed configuration items that are installed only on demand.

A detailed example:

  • Say there are two feature modules that both include a body field. The first, distro1_event, has that field attached to an event content type, while the second, distro2_article, has it attached to an article content type. Each of these features will need to be dependent on a module that provides the body field storage.
  • A common solution to this need is the use of a base feature. So there night be distro1_base and distro2_base, each of which contains the body field storage and each of which is required by any feature in their feature set that includes a body field. In this case, distro1_event would require distro1_base and distro2_article would require distro2_base.
  • Consequently, distro1_event and distro2_article cannot be installed on the same site, since their dependencies conflict.
  • However, if the body field storage is instead added to a shared configuration module - Compatible - that registers itself for handling by config_share, both distro1_event and distro2_article can safely introduce a dependency on Compatible and will get the body field storage on an as-needed basis. Specifically, even though Compatible may include many other configuration items, they will not be installed unless they are specifically required because they are configuration dependencies.

Configuration Share overrides the standard ConfigInstaller service to provide a custom version of ConfigInstaller::getConfigToCreate(), the method that determines what configuration should be installed when a given extension is enabled.

When any extension is installed, the configuration to install is analyzed for dependencies. If any of the dependencies is provided by a module that provides shared configuration, that dependency is added to the list of configuration to install.

Developer usage

To provide shared configuration

The Compatible module is intended to be the standard repository for shared configuration.

However, it's easy to create a custom shared repository, which might be an interim step while waiting for candidate additions to Compatible to be accepted.

To provide shared configuration from a custom module:

  1. Edit the module's info file and add configuration_share to its list of dependencies.
     - config_share

    Note that if the shared configuration you're adding itself has module dependencies, you should not add these to the Compatible module or to your custom module that provides shared configuration, because doing so would create dependencies that would be needed only if the shared configuration is itself installed. For example, if you're adding a field storage that depends on the Geolocation module, this dependency should not go in the module providing the shared configuration. Instead, you will add the module dependency to the module that requires the shared configuration--for example, a module that provides a field that requires the shared field storage. See below.

  2. Create the directory config/shared within your module and place shared configuration there.

Now the configuration in config/shared will be installed only when it's required by other configuration being installed.

To use shared configuration

The following pointers assume you're using the Compatible module to provide shared configuration.

  • Determine if any configuration required by the configuration you're providing is either already in Compatible or is a candidate for adding to Compatible. Candidate configuration is configuration that:
    • Is commonly required as a dependency to meet multiple distinct areas of functionality. For example. a field_image field storage is the base of fields that are typically attached to multiple content types, and so is a good candidate.
  • In your extension, add a dependency on Compatible.
     - compatible
  • If the shared configuration that your configuration requires has module dependencies, add those also to the .info.yml module. For example, if you're using a field that requires a field storage that requires the Geolocation module, you would add:
     - geolocation
  • If the item you want to use is not already included in the config/shared directory of Compatible, and there is not an existing issue, export the item and open an issue of type "Shared configuration items" on the Compatible project with a patch to add it.
  • Review the configuration you're adding and ensure it has a full list of config dependencies. If not, add any dependencies that are missing. For example, currently, the Full HTML filter format provided by the Standard install profile in core requires the Administrator role but is missing the corresponding dependency in its dependency information due to #2569741: FilterFormat should add the roles as config dependencies. To add the needed dependency, change the dependency information from
        - editor


        - user.role.administrator
        - editor

That's it. Assuming your patch, if you submitted one, is accepted, the base configuration your extension requires will now be installed on demand.

Related modules

  • Features 3.x for Drupal 8 facilitates building interoperable features and distributions.
  • Apps Compatible is roughly an equivalent of Configuration Share for Drupal 7.
Supporting organizations: 

Project information