Config Actions

What is a config action?

A config action is a way of altering configuration. The main use case of config actions are to alter configuration in a Drupal recipe.

A module or another recipe has provided a piece of configuration. Now the recipe you're applying needs to alter that configuration.

An example is to add permissions to a user role from an article recipe that provides an article content type. As it runs, the article recipe applies a number of other recipes, one of which provides a content_editor role. Now the article recipe needs to add article-related permissions to that existing content_editor role.

The config actions API in Drupal core provides a flexible system for creating different types of actions. Initially, there are two sets of actions supported by the API.

1. Actions that can be applied to configuration of any configuration entity type.
2. Actions declared for methods of specific configuration entity types. These actions are created by adding PHP attributes to a method declaration.

Config entity actions can have a plural as well as a singular form. For example, the plural form of the grantPermission action is grantPermissions. Config action names should be lower camel cased.

Format of config actions

Config actions are declared in the recipe.yml file of a Drupal recipe.

The structure for each action has three parts:

1. Configuration entity ID.
2. The action, which must be one that's declared for the entity type of the configuration entity.
3. Action arguments, which take different forms depending on:
   • the number of arguments that the action takes, and
   • whether the action is in the singular or plural form.

The basic format for a singular action that takes only one argument is:

config:
  actions:
    some.config.id:
      someAction: 'some argument'

The grantPermission action is derived from the \Drupal\user\Entity\Role::grantPermission() method which, per its API documentation, takes only a single argument, $permission. So here's how the action looks in the singular when used to grant a permission to the editor user role:

config:
  actions:
    user.role.editor:
      grantPermission: 'delete any article content'

In the plural form, the argument is not a single string but an array of them, each of which will be applied to a separate ::grantPermission() call. Here's how that looks:

config:
  actions:
    user.role.editor:
      grantPermissions:
        - 'delete any article content'
        - 'edit any article content'

When the action's method accepts more than one argument, the arguments are passed as an array. An example is the setComponent action for entity view and form displays.

The EntityDisplayBase::setComponent() method takes two arguments:

string $name: The name of the component. array $options: The display options.

So in the singular the action passes a list of arguments, first a string and then an array. A sample action adding field_tags configuration to the default view display for the article content type might look like this:

config:
  actions:
    core.entity_view_display.node.article.default:
      setComponent:
        name: field_tags
        options:
          type: entity_reference_label
          label: above
          settings:
            link: true
          third_party_settings: {  }
          weight: 10
          region: content

A pluralized version, adding the configuration for multiple fields to the same display, would pass an array of arrays:

config:
  actions:
    core.entity_view_display.node.article.default:
      setComponents:
        -
          name: field_tags
          options:
            type: entity_reference_label
            label: above
            settings:
              link: true
            third_party_settings: {  }
            weight: 10
            region: content
        -
          name: field_categories
          options:
            type: entity_reference_label
            label: above
            settings:
              link: true
            third_party_settings: {  }
            weight: 11
            region: content

Adding support for new config entity actions

To create an action for an existing config entity method, you add a PHP attribute to the method declaration. At a minimum, you need to provide an admin label for the action.

For example, the Role::grantPermission() method is exposed as a config action through the following code that comes immediately before the function declaration (public function grantPermission($permission) {):

#[ActionMethod(adminLabel: new TranslatableMarkup('Add permission to role'))]

The PHP attribute uses two class names. Depending on whether the class file you're editing already has them, you may need to add a use statement for one or both of these classes. Example:

use Drupal\Core\Config\Action\Attribute\ActionMethod;
use Drupal\Core\StringTranslation\TranslatableMarkup;

By default, a pluralized version of the action name will also be generated using Symfony's English string inflector.

If the method name doesn't lend itself to automatic pluralization, you can explicitly pass a plural form. Take for example a ::set() method. Since sets doesn't fit here, the PHP attribute could be:

#[ActionMethod(adminLabel: new TranslatableMarkup('Set a property on the configuration item'), pluralize: 'setMultiple')]

If it doesn't make logical sense to support a pluralized form, you can pass a value of FALSE:

#[ActionMethod(adminLabel: new TranslatableMarkup('Do something'), pluralize: FALSE)]

For notes on how to determine what config actions are needed for particular config entity changes, see the section "Convert config overrides to config actions" in the recipe author guide.

Config Actions List

Please visit the Config Actions List