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

Configuration entities can depend on modules, themes and other configuration entities. The dependency system is used during configuration installation to ensure that configuration entities are imported in the correct order. For example, node types are created before their fields and the fields are created before their field instances.

Dependencies are stored to the configuration entity's configuration object so that they can be checked without the module that provides the configuration entity class being installed. This is important for configuration synchronization which needs to be able to validate configuration in the sync directory before the synchronization has occurred.

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\Config\Entity\EntityWithPluginBagInterface.

The configuration manager service provides methods to find dependencies for a specified module, theme or configuration entity.

Example implementation: Block

  /**
   * {@inheritdoc}
   */
  public function calculateDependencies() {
    parent::calculateDependencies();
    $this->addDependency('theme', $this->theme);
    return $this->dependencies;
  }

The implementation in \Drupal\block\Entity\Block creates a dependency on the theme set in the block's theme property. Block's implement \Drupal\Core\Config\Entity\EntityWithPluginBagInterface so the dependency on the module the that provides the block plugin is added by \Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies().

dependencies:
  module:
    - user
  theme:
    - bartik

The dependencies written to the block.block.bartik_login configuration in the Standard Profile.

For a much more complicated implementation see \Drupal\entity\EntityDisplayBase::calculateDependencies() which creates dependencies on fields, formatter or widget providers, display or form modes, and the entity providing the target entity type's bundle.

Finding dependent entities

The config manager service has two methods; findConfigEntityDependents() and findConfigEntityDependentsAsEntities().

  $dependents = \Drupal::service('config.manager')->findConfigEntityDependents('module', array('node', 'user'));

Finds configuration entities dependent on either the Node module OR the User module. This includes entities that do not have a direct dependency on the Node or User modules but are dependent on a configuration entity that does. The return type of this function is an array of \Drupal\Core\Config\Entity\ConfigEntityDependency objects. \Drupal\Core\Config\Entity\ConfigEntityDependency is a lightweight value object containing all the information needed to calculate an configuration entities dependencies.

  $dependents = \Drupal::service('config.manager')->findConfigEntityDependentsAsEntities('entity', array('node.type.article'));

Finds configuration entities dependent on the node.type.article configuration entity. This includes entities that do not have a direct dependency on node.type.article but are dependent on a configuration entity that does. The return type of this function is an array of configuration entity objects.

Impacts: 
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