Configuration API in Drupal 8

Same name and namespace in other branches

1. 9 core/core.api.php \config_api

Information about the Configuration API.

The Configuration API is one of several methods in Drupal for storing information. See the Information types topic for an overview of the different types of information. The sections below have more information about the configuration API; see https://www.drupal.org/docs/drupal-apis/configuration-api for more details.

Configuration storage

In Drupal, there is a concept of the "active" configuration, which is the configuration that is currently in use for a site. The storage used for the active configuration is configurable: it could be in the database, in files in a particular directory, or in other storage backends; the default storage is in the database. Module developers must use the configuration API to access the active configuration, rather than being concerned about the details of where and how it is stored.

Configuration is divided into individual objects, each of which has a unique name or key. Some modules will have only one configuration object, typically called 'mymodule.settings'; some modules will have many. Within a configuration object, configuration settings have data types (integer, string, Boolean, etc.) and settings can also exist in a nested hierarchy, known as a "mapping".

Configuration can also be overridden on a global, per-language, or per-module basis. See https://www.drupal.org/node/1928898 for more information.

Configuration YAML files

Whether or not configuration files are being used for the active configuration storage on a particular site, configuration files are always used for:

• Defining the default configuration for an extension (module, theme, or profile), which is imported to the active storage when the extension is enabled. These configuration items are located in the config/install sub-directory of the extension. Note that changes to this configuration after a module or theme is already enabled have no effect; to make a configuration change after a module or theme is enabled, you would need to uninstall/reinstall or use a hook_update_N() function.
• Defining optional configuration for a module or theme. Optional configuration items are located in the config/optional sub-directory of the extension. These configuration items have dependencies that are not explicit dependencies of the extension, so they are only installed if all dependencies are met. For example, in the scenario that module A defines a dependency which requires module B, but module A is installed first and module B some time later, then module A's config/optional directory will be scanned at that time for newly met dependencies, and the configuration will be installed then. If module B is never installed, the configuration item will not be installed either.
• Exporting and importing configuration.

The file storage format for configuration information in Drupal is YAML files. Configuration is divided into files, each containing one configuration object. The file name for a configuration object is equal to the unique name of the configuration, with a '.yml' extension. The default configuration files for each module are placed in the config/install directory under the top-level module directory, so look there in most Core modules for examples.

Configuration schema and translation

Each configuration file has a specific structure, which is expressed as a YAML-based configuration schema. The configuration schema details the structure of the configuration, its data types, and which of its values need to be translatable. Each module needs to define its configuration schema in files in the config/schema directory under the top-level module directory, so look there in most Core modules for examples.

Configuration can be internationalized; see the Internationalization topic for more information. Data types label, text, and date_format in configuration schema are translatable; string is non-translatable text (the 'translatable' property on a schema data type definition indicates that it is translatable).

Simple configuration

The simple configuration API should be used for information that will always have exactly one copy or version. For instance, if your module has a setting that is either on or off, then this is only defined once, and it would be a Boolean-valued simple configuration setting.

The first task in using the simple configuration API is to define the configuration file structure, file name, and schema of your settings (see Configuration YAML files above). Once you have done that, you can retrieve the active configuration object that corresponds to configuration file mymodule.foo.yml with a call to:

$config = \Drupal::config('mymodule.foo');

This will be an object of class \Drupal\Core\Config\Config, which has methods for getting configuration information. For instance, if your YAML file structure looks like this:

enabled: '0'
bar:
  baz: 'string1'
  boo: 34

you can make calls such as:

// Get a single value.
$enabled = $config
  ->get('enabled');

// Get an associative array.
$bar = $config
  ->get('bar');

// Get one element of the array.
$bar_baz = $config
  ->get('bar.baz');

The Config object that was obtained and used in the previous examples does not allow you to change configuration. If you want to change configuration, you will instead need to get the Config object by making a call to getEditable() on the config factory:

$config = \Drupal::service('config.factory')
  ->getEditable('mymodule.foo');

Individual configuration values can be changed or added using the set() method and saved using the save() method:

// Set a scalar value.
$config
  ->set('enabled', 1);

// Save the configuration.
$config
  ->save();

Configuration values can also be unset using the clear() method, which is also chainable:

$config
  ->clear('bar.boo')
  ->save();
$config_data = $config
  ->get('bar');

In this example $config_data would return an array with one key - 'baz' - because 'boo' was unset.

Configuration entities

In contrast to the simple configuration settings described in the previous section, if your module allows users to create zero or more items (where "items" are things like content type definitions, view definitions, and the like), then you need to define a configuration entity type to store your configuration. Creating an entity type, loading entities, and querying them are outlined in the Entity API topic. Here are a few additional steps and notes specific to configuration entities:

• For examples, look for classes that implement \Drupal\Core\Config\Entity\ConfigEntityInterface -- one good example is the \Drupal\user\Entity\Role entity type.
• In the entity type annotation, you will need to define a 'config_prefix' string. When Drupal stores a configuration item, it will be given a name composed of your module name, your chosen config prefix, and the ID of the individual item, separated by '.'. For example, in the Role entity, the config prefix is 'role', so one configuration item might be named user.role.anonymous, with configuration file user.role.anonymous.yml.
• You will need to define the schema for your configuration in your modulename.schema.yml file, with an entry for 'modulename.config_prefix.*'. For example, for the Role entity, the file user.schema.yml has an entry user.role.*; see Configuration YAML files above for more information.
• Your module can provide default/optional configuration entities in YAML files; see Configuration YAML files above for more information.
• Some configuration entities have dependencies on other configuration entities, and module developers need to consider this so that configuration can be imported, uninstalled, and synchronized in the right order. For example, a field display configuration entity would need to depend on field configuration, which depends on field and bundle configuration. Configuration entity classes expose dependencies by overriding the \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies() method.
• On routes for paths starting with '/admin' or otherwise designated as administration paths (such as node editing when it is set as an admin operation), if they have configuration entity placeholders, configuration entities are normally loaded in their original language, without translations or other overrides. This is usually desirable, because most admin paths are for editing configuration, and you need that to be in the source language and to lack possibly dynamic overrides. If for some reason you need to have your configuration entity loaded in the currently-selected language on an admin path (for instance, if you go to example.com/es/admin/your_path and you need the entity to be in Spanish), then you can add a 'with_config_overrides' parameter option to your route. The same applies if you need to load the entity with overrides (or translated) on an admin path like '/node/add/article' (when configured to be an admin path). Here's an example using the configurable_language config entity:

  mymodule.myroute:
    path: '/admin/mypath/{configurable_language}'
    defaults:
      _controller: '\Drupal\mymodule\MyController::myMethod'
    options:
      parameters:
        configurable_language:
          type: entity:configurable_language
          with_config_overrides: TRUE
  

With the route defined this way, the $configurable_language parameter to your controller method will come in translated to the current language. Without the parameter options section, it would be in the original language, untranslated.

See also

Internationalization

File

core/core.api.php, line 201

Documentation landing page and topics, plus core library hooks.

Classes

Interfaces