Configuration entity dependencies

Configuration entities may declare dependencies. A dependency can be a module, a theme or an entity.

A configuration entity's dependencies must be installed before the configuration entity can be installed. If the dependencies are not present and installed in the site, the configuration entity will fail to install. A module should declare in its info YAML file module and theme dependencies that its configuration entities will require.

Generally, module developers will not need to concern themselves with declaring dependencies for configuration entities. By extending core configuration entity base classes and creating plugins from standard plugin API providers, dependencies will be calculated and declared automatically.

Overview

Configuration entity dependencies are declared through the config_dependencies key in a configuration entity's definition. The keys of this array may be one of:

• content
• config
• module
• theme

Configuration entities determine their dependencies by implementing \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies(). This method should be called from the configuration entity's implementation of \Drupal\Core\Entity\EntityInterface::preSave(). Implementations should use the helper method \Drupal\Core\Config\Entity\ConfigEntityBase::addDependency() to add dependencies. All the implementations in core call the parent method \Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies(), which resets the dependencies and provides an implementation to determine the plugin providers for configuration entities that implement \Drupal\Core\Entity\EntityWithPluginCollectionInterface. See the configuration dependency manager API documentation for more detail on these classes and methods.

How configuration dependencies are calculated

Calculating dependencies based on config entity properties

@todo - see \Drupal\block\Entity\Block::calculateDependencies

Calculating dependencies based on other config entities

@todo - see \Drupal\entity\EntityDisplayBase::calculateDependencies (this is a super complex example of this)

Calculating dependencies in plugins and their derivatives

@todo see Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies - flesh out the fact that if the config entity implements EntityWithPluginCollectionInterface then a dependency will automatically be added on the module that provides the plugin.

Plugin derivative definitions are derived from a base plugin. For example, the \Drupal\system\Plugin\Derivative\SystemMenuBlock is a plugin derivative of the \Drupal\system\Plugin\Block\SystemMenuBlock plugin. System menu blocks require that a dependency relationship be established between the plugin block configuration entity and the menu configuration entity exposed through the block.

\Drupal\system\Plugin\Block\SystemMenuBlock implements the getDerivativeDefinitions() method. So derivative menu blocks, such as the Bartik footer menu block, will all have a dependency on the corresponding \Drupal\system\Entity\Menu entity.

public function getDerivativeDefinitions($base_plugin_definition) {
  foreach ($this->menuStorage->loadMultiple() as $menu => $entity) {
    $this->derivatives[$menu] = $base_plugin_definition;
    $this->derivatives[$menu]['admin_label'] = $entity->label();
    $this->derivatives[$menu]['config_dependencies']['config'] = array($entity->getConfigDependencyName());
  }
  return $this->derivatives;
}

In the code above, each system menu block derivative is assigned a configuration dependency of the entity that provides the block's menu. To get the name of the entity that should be used to identify the configuration dependency, the entity's getConfigDependencyName() method is invoked. An entity's name is a composed string and should not be hard-coded where the dependency is declared.

The config_dependencies property may also be declared as part of a plugin's definition. However, configuration entity dependencies mostly are dynamic values and thus calculated. Declaring a static dependency in the plugin's definition is anticipated to be rare and should be avoided.

Enforced dependencies

@todo -- See https://www.drupal.org/node/2404447

See Managing configuration in Drupal 8 for more information about exporting and importing configuration files.