Configuration Object dependencies

Configuration objects can declare dependencies. A dependency can be a module, theme, or entity.

A configuration object’s dependencies must be present before the configuration object can be installed. If the required dependencies are missing on the site, the configuration object will fail to install. A module must declare in its module info YAML file any module or theme dependencies required by its configuration objects.

Generally, module developers do not need to worry about manually declaring dependencies for configuration objects. By extending the core configuration entity base classes and using plugins from standard plugin API providers, dependencies will be automatically calculated and declared.

Overview

A configuration object’s dependencies are declared using the config_dependencies key in the configuration definition. The keys of this array can be the following:

• content
• config
• module
• theme

Configuration objects define their dependencies by implementing \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies(). This method should be called from the object’s implementation of \Drupal\Core\Entity\EntityInterface::preSave(). Implementations should use the helper method \Drupal\Core\Config\Entity\ConfigEntityBase::addDependency() to add dependencies. All core implementations call the parent method \Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies(), which clears dependencies and provides a way to determine plugin providers for configuration objects implementing \Drupal\Core\Entity\EntityWithPluginCollectionInterface. See the ConfigDependencyManager API documentation for more details on these classes and methods.

How Configuration Dependencies Are Calculated

Calculating Dependencies Based on Configuration Object Properties

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

Calculating Dependencies Based on Other Configuration Objects

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

Calculating Dependencies in Plugins and Their Derivatives

@todo – see Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies – note that if a config object implements EntityWithPluginBagInterface, it will automatically add a dependency on the module that provides the plugin.

Plugin derivative definitions are derived from the base plugin. For example, \Drupal\system\Plugin\Derivative\SystemMenuBlock is a derivative of \Drupal\system\Plugin\Block\SystemMenuBlock. System menu blocks require a dependency relationship between the block module’s configuration object and the menu configuration object provided through the block.

\Drupal\system\Plugin\Block\SystemMenuBlock implements getDerivativeDefinitions(). Therefore, menu block derivatives such as the Bartik footer menu block will depend 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 config dependency on the object that provides the menu. To get the correct entity name to use for the config dependency, the getConfigDependencyName() method is called. The name is a composite string and should not be hardcoded where the dependency is declared.

The config_dependencies property can also be declared in the plugin definition. However, configuration object dependencies are typically dynamic values and thus calculated. Declaring static dependencies in plugin definitions is rare and should be avoided.

Forced Dependencies

@todo – see https://www.drupal.org/node/2404447.

See Configuration Management in Drupal 8 for more on exporting and importing configuration files.