Configuration

Configuration means the settings of the site and its modules: the site name, the number of articles per page, a greeting text. Drupal keeps them in the database but can export them to YAML files and move them between sites together with the code. The settings of your own module are kept in configuration too, not in PHP constants.

Default values

When a module is enabled, Drupal reads the files from the config/install folder and writes them to the database. Create the folders and the file by hand:

# web/modules/custom/blog/config/install/blog.settings.yml
list_title: 'Latest articles'
items_per_page: 10
words_per_minute: 200

The file name without .yml is the name of the configuration object: blog.settings. By convention it starts with the module name.

The schema

The schema describes the type of each value. Drupal validates settings against it and learns which strings can be translated:

# web/modules/custom/blog/config/schema/blog.schema.yml
blog.settings:
  type: config_object
  label: 'Blog settings'
  mapping:
    list_title:
      type: label
      label: 'List title'
    items_per_page:
      type: integer
      label: 'Articles per page'
    words_per_minute:
      type: integer
      label: 'Words per minute'

There is one schema file per module, and it describes all its configuration objects. The label type is a short translatable string, string is a non-translatable one, boolean is yes or no.

Applying

The config/install folder is read only at the moment the module is enabled. The blog module is already enabled, so it has to be enabled again:

vendor/bin/drush pmu blog -y
vendor/bin/drush en blog -y

You can check that the settings were written with a command:

vendor/bin/drush config:get blog.settings

It prints the three values from the file.

Reading

// web/modules/custom/blog/src/Controller/BlogController.php
public function list(): array
{
    $config = $this->config('blog.settings');
 
    return [
        '#markup' => $config->get('list_title'),
    ];
}

The /blog page shows "Latest articles". The $this->config() method exists in controllers and forms. Hooks use \Drupal::config('blog.settings'), and services use the config.factory service, as in the lesson about services.

Writing

// anywhere, for example in blog.module
\Drupal::configFactory()
    ->getEditable('blog.settings')
    ->set('items_per_page', 20)
    ->save();

The object from config() is read-only. Configuration is changed through getEditable(), and save() must be called. From the terminal the same is done by drush config:set blog.settings items_per_page 20.

Configuration and state

Not everything that has to be remembered is configuration.

Storage	What to keep	Moves between sites
Configuration	Settings the administrator chooses	Yes
State	Internal values: the time of the last mailing	No
Content	Nodes, users	No

State is read and written like this:

// anywhere, for example in blog.module
\Drupal::state()->set('blog.last_mailing', time());
 
$last = \Drupal::state()->get('blog.last_mailing', 0);

The second argument of get() is the value used when nothing has been written yet.

Common mistake

You changed config/install/blog.settings.yml, rebuilt the cache — and the site returns the old values. The files in config/install are only starting values: once the module is enabled, the real settings live in the database, and drush cr does not touch them. Change a value through drush config:set, the settings form or by reinstalling the module.

Thanks for reading!