Configuration file coding standards
This page covers:
- Standards related to configuration files in Drupal 8 (and presumably later versions of Drupal).
Note: Before making any changes to the standards in this document, please file an issue in the Drupal issue queue, with component "documentation", and tagged "coding standards" and "Configuration system", so your proposed changes can be discussed.
Contents of this page - notes and standards section:
Notes and standards
The standards on this page are related to the YAML files used to store Drupal configuration, starting in Drupal 8.x. Here are a few background notes on the configuration API:
- The file name for a configuration object is equal to the unique name of the configuration, with a '.yml' extension.
- Each configuration file has a specific structure, which is expressed as a YAML-based configuration schema.
- You can retrieve a configuration object by calling:
$config = \Drupal::config('mymodule.foo');
(or equivalent calls to the Drupal container if you are using dependency injection), passing in the unique name for the configuration. This will give you an associative array, often with multiple levels of hierarchy. With that object, you can then call:
$value = $config->get('top_level'); $value = $config->get('top_level.next_level.another_level');
etc. to get the values from the configuration object.
- Configuration can be simple configuration, like
foo.settingsor configuration entities.
- For more details on the configuration API, see
The configuration file name is equal to the unique configuration name, with
The unique configuration name cannot exceed 250 characters.
For simple configuration, by convention the unique configuration name should start with the extension name (the machine name of the module, theme, or install profile that owns the configuration). Usually, the choice of name is
(extension).settings for the unique configuration name, but this is not required. Extensions can also have multiple configuration files, if separating them makes logical sense.
For configuration entities, the unique configuration name has a prefix, which is equal to
(extension) is the machine name of the module that defines the config entity, or "core" for core entities;
(config_prefix) is defined in the entity annotation, and defaults to the machine name (ID) of the config entity if it has not been overridden by a
config_prefix annotation in the entity class. Extension names cannot exceed 50 characters, and config entity config prefixes cannot exceed 32 characters.
The rest of the unique configuration name for a config entity (which is called the suffix in the rest of this section) is limited to 150 characters.
For many configuration entities, the suffix consists solely of the individual machine name of the item. For instance, the unique configuration name for an image style is
image.style.(machine_name_of_style), and for a view it is
views.view.(machine_name_of_view). In these cases, the machine name of the item cannot exceed 150 characters.
For entity bundles, the unique configuration name for the bundle configuration is
(extension) is the module that defines the entity (or "core"),
(entity_id) is the machine name of the entity this is a bundle of,
(bundle_config_prefix) is the config prefix defined in the bundle configuration entity class annotation (defaulting to the config entity ID if not defined), and
(bundle_machine_name) is the machine name of that particular bundle. So for example, the unique configuration name for the Book module's "book" content type for nodes is
node.type.book, because the config prefix for the NodeType entity is "type", and the node type's machine name in this case is "book". Entity and bundle IDs and config prefixes are limited to 32 characters.
For configuration like field instances and view modes, it's an even more complex structure. For instance, the view mode structure is
entity.view_mode.(target_entity_type).(view_mode_machine_name) (example: entity.view_mode.node.teaser), and field instances are
field.instance.(target_entity_type).(target_bundle).(field_machine_name) (example: field.instance.node.article.body). In these cases, sensible maximums need to be chosen for each component of the unique configuration name, so that the suffix portion does not exceed 150 characters.
Config files use YAML syntax and .yml extension.
Comments are not typically in config files, but can be made using #.
Use two spaces to indent in config files. In YAML, the white space has semantic meaning to represent nested structures.