Defining and Using Your Own Configuration in Drupal

Main Topic: Defining Your Own Configuration

You can include default configuration in your module based on the functionality of other modules (content types, views, fields, text formats, etc.).
For example, the Node module provides a content type configuration, so in your own module, you define a default content type that can be shipped with your module.

You might also want to define configuration for your own plugins, entities, and settings, which in turn can be used by other modules, just like you can use the Node content type configuration. Drupal 8 makes defining your own configuration straightforward.

Configuration File

Configuration files for your module are located in the config/install subdirectory of your module. For example: /modules/example/config/install/example.settings.yml, if your module is located in /modules/example. You can place your module’s configuration files here using the YAML file format.

While it is not mandatory, it is strongly recommended to name the configuration files you define for your module using your module's own name as a prefix: for example, example.settings.yml for configuration settings. Do not name your file settings.yml or system.settings.yml, as this could conflict with files from other modules. Not following this convention can confuse Drush commands such as drush config:import.

This also allows you to ship configuration for other components, for example, a sample content type, including default configuration in your module, where the config file would be named node.type.example_mytype.yml, identifying it as a Node type handled by the Node module.

The file name (excluding the .yml extension) is also the configuration name in the system and is how you access your configuration in the PHP API.

Configuration File Structure

The configuration file should use the YAML format. You can structure your configuration file according to your needs—there are no limitations beyond YAML itself. For example, if you need a setting to print something special from your page controller, the file may contain a message key with a string value:

message: 'Hello'
langcode: 'en'

It is recommended to include the language code under the langcode key. This is used by the language system to suggest translatable text for translation. The langcode key is reserved for this purpose and should not be used for anything else at the top level of the file.

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

To make the configuration translatable, you need to add two more files:

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

The first defines the schema of your custom configuration. We'll define example.settings as a config_object containing several fields. Each field has a type, and the base type definition determines whether it is translatable (see core.data_types.schema.yml). For example, path (an internal Drupal path) is not translatable, while text is.

# /modules/example/config/schema/example.schema.yml
example.settings:
  type: config_object
  label: 'Example config'
  mapping:
    message:
      type: text
      label: 'Message'

The second adds a link to /admin/config/regional/config-translation for the appropriate translation form:

# /modules/example/example.config_translation.yml
example.admin.config:
  title: 'Example module'
  base_route_name: example.admin.config
  names:
    - example.settings

By convention, the key matches the base route name: example.admin.config is the route name to your module's admin config form. The names list includes all config keys edited on the form—in this case, your custom configuration defined above.

The file can include more complex lists and key/value pairs in a tree structure. See for example views.view.content.yml for a moderately complex config file example.

The configuration translation module automatically adds a “Translate” tab to your module’s config form. However, it may not appear if it’s the only available tab. To add a “default” tab for the config form, you need to define another file: example.links.task.yml. (See Module-defined local tasks.)

# example.links.task.yml
example.admin.config:
  route_name: example.admin.config
  title: Settings
  base_route: example.admin.config

Using Configuration

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

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

If you want to edit the configuration and save a new value, 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

• Configuration API in Drupal 8