Defining and using your own configuration in Drupal 8

Last updated on
21 September 2016

Main topic described: defining own configuration

You can include default configuration in your module based on functionality in other modules (node types, views, fields, text formats, etc).
For example, node module provides a node type configuration, so in your own module you configure a default node type that can be supplied with your module.

You may want to define configuration for your own plugins, entities and settings, which can in turn be utilised by other modules, just as you can utilise node's content type configuration. Drupal 8 makes defining your own piece of configuration really simple.

The configuration file

Configuration files for your module reside in the config/install subdirectory of your module. Such as /modules/example/config/install/example.config.yml if your module is in /modules/example. You can place your own module's configuration files here using the YAML file format.

Although this is not enforced, it is strongly suggested that you name configuration files that you define for your module using a prefix of your own module name: example.settings.yml for example for configuration settings. Do not name the file settings.yml or system.settings.yml as that would possibly conflict with file names elsewhere. This also allows you to ship with configuration for other components, such as the node type example from including default configuration in your module where the configuration file was node.type.example_mytype.yml identifying the configuration file to be handled as a node type by node module.

The name of the configuration file (minus the .yml file extension) is also called the configuration name in the system and that is how you can refer to your configuration from the PHP API.

Structure of the configuration file

The configuration file should use the YAML file format. You can structure your own configuration file based on your own needs, there are no restrictions beyond the YAML format itself on the structure. Eg. if you need a setting to output something custom from your page controller, the file may include a message key with a string value:

message: 'Hello'
langcode: 'en'

It is best practice to include the language code of the file under a langcode key. This is used by the language system to offer translatable text up for translation. The langcode key is reserved for this purpose and you should not use it on the top level of the file for anything else.

In order to make the message translatable you need to include two more files:

- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml

The first one allows you to declare which parts of your configuration should be translatable:

example.config:
  type: config_object
  label: 'Example config'
  mapping:
    message:
      type: text
      label: 'Message'

The second one adds a link on /admin/config/regional/config-translation to the corresponding translation form:

hello.config:
  title: 'Example Translatable config'
  base_route_name: example.admin.config
  names:
    - example.config

example.admin.config is the name of the route to the admin config form of your module.

The file can include more complex lists and key/value pairs in a tree structure. See for example the views.view.content.yml file for an example configuration file with quite a bit of complexity.

Using the configuration

Drupal 8 comes with a PHP API to read and write this configuration. The simplest way to use this is the Drupal::config() static method:

$config = \Drupal::config('example.settings');
// Will print 'Hello'.
print $config->get('message');
// Will print 'en'.
print $config->get('langcode');

If you want to edit a configuration and update it with a new value you can use the \Drupal::service('config.factory')->getEditable() method:

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

// Set and save new message value.
$config->set('message', 'Hi')->save();

// Now will print 'Hi'.
print $config->get('message');

See also