Defining and using your own configuration in Drupal

Last updated on

22 February 2024

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 utilized by other modules, just as you can utilize node's content type configuration.

The configuration file

Configuration files for your module reside in the config/install subdirectory of your module. Thus, /modules/mymodule/config/install/mymodule.settings.yml if your module is in /modules/mymodule. 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: mymodule.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. If you don't follow this convention, Drush commands such as drush config:import will be confused.

This also allows you to ship with configuration for other components, such as the node type mymodule from including default configuration in your module where the configuration file was node.type.mymodule.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 Config 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.

Translatable configuration

To translate the configuration, the Configuration Translation module must be installed.

In order to make the configuration translatable you need to add two more files:

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

The first one defines the schema of the custom configuration. We define mymodule.settings as a config_object containing a number of fields. Each field has a type: the underlying type definition determines whether the field will be translatable or not (see core.data_types.schema.yml). For example a path field containing a Drupal internal path is not translatable, but a text field is.

# /modules/mymodule/config/schema/mymodule.schema.yml file:

mymodule.settings:
  type: config_object
  label: 'Configuration of my module'
  mapping:
    message:
      type: text
      label: 'Message'

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

# /modules/mymodule/mymodule.config_translation.yml file:

mymodule.admin.config:
  title: 'My module'
  base_route_name: mymodule.admin.config
  names:
    - mymodule.settings

The key is by convention the same as the base route name: mymodule.admin.config is the name of the route to the admin config form of your module. names lists all the configuration keys that are edited in the form, in this case the custom config defined in the schema above.

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.

Configuration Translation automatically adds a "translate module" tab to the module configuration form, however it may not be visible if it is the only tab available. To add a "default" tab for the configuration form, we need to add another file mymodule.links.task.yml. (See Module defined local tasks.)

// mymodule.links.task.yml file:

mymodule.admin.config:
  route_name: mymodule.admin.config
  title: Settings
  base_route: mymodule.admin.config

Using the configuration

The simplest way to use this is the Drupal::config() static method:

$config = \Drupal::config('mymodule.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('mymodule.settings');

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

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