Simple Configuration API

Using $config in the Context of a Form

This page describes the API for retrieving and setting configuration data for simple configuration. (This does not apply to information stored in configuration objects.)

Configuration Data

Each module can provide default configuration. For example, maintenance mode settings are defined in core/modules/system/config/install/system.maintenance.yml. In this file, the first part represents the namespace of the module providing the configuration (system module in this case), followed by a subsystem (maintenance). The file must reside in the config/install directory. It must also contain a period “.” in the filename to pass validation in ConfigBase->validateName($name). This file contains the following YAML:

message: '@site is currently under maintenance. We should be back shortly. Thank you for your patience.'
langcode: en

Configuration can also be nested, as in performance settings (system.performance.yml):

cache:
  page:
    enabled: '0'
    max_age: '0'
preprocess:
  css: '0'
  js: '0'
response:
  gzip: '0'

IMPORTANT: Root keys must be a mapping

Top-level configuration data must be a mapping rather than an unpredictable sequence. For example, if you're storing data for each available entity type, make the parent key the entity type and include a root key like entity_type. See layout example below:

entity_type:
  commerce_order:
    foo: 'bar'
  node:
    foo: 'bar'
  user:
    foo: 'bar'

If entity types are the root key, it's not possible to define the configuration using a schema. Also, core won't be able to add metadata when configuration is installed during module (or theme) installation.

Interacting with Configuration

You interact with these files through the Config object by calling the config() function with the filename (minus the extension). The config function returns an instance of \Drupal\Core\Config\ImmutableConfig.

// Immutable Config (Read Only).
$config = \Drupal::config('system.performance');

// Mutable Config (Read / Write).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Once you have a Config object, you can interact with it in various ways.

Reading Configuration

Configuration is read using the get() method. To read a specific key:

$config = \Drupal::config('system.maintenance');
$message = $config->get('message');

Calls to \Drupal::config() can also be chained:

$message = \Drupal::config('system.maintenance')->get('message');

To read nested configuration, use dot notation:

$enabled = \Drupal::config('system.performance')->get('cache.page.enabled');

To read a group of nested data:

$page_cache = \Drupal::config('system.performance')->get('cache.page');

This returns an array with the keys “enabled” and “max_age”.

To return all data from a configuration object:

$data = \Drupal::config('system.performance')->get();

You can also list all available configuration keys in the system, or only those that start with a specific substring:

$keys = \Drupal::service('config.factory')->listAll($prefix = "");

Writing Configuration

To modify configuration, get an instance of \Drupal\Core\Config\Config (a mutable config object) using getEditable(). Attempting to modify an \Drupal\Core\Config\ImmutableConfig or calling delete()/save() on it will throw an ImmutableConfigException.

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

To write or modify data:

// Set a scalar value.
$config->set('cache.page.enabled', 1);

// Set an array of values.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Save to database.
$config->save();

You can also chain set() and save():

\Drupal::service('config.factory')->getEditable('system.performance')->set('cache.page.enabled', 1)->save();

To replace the entire configuration object, use setData():

\Drupal::service('config.factory')->getEditable('system.performance')->setData([
  'cache' => [
    'page' => [
      'enabled' => '0',
      'max_age' => '0',
    ],
  ],
  'preprocess' => [
    'css' => '0',
    'js' => '0',
  ],
  'response' => [
    'gzip' => '0',
  ],
])->save();

Deleting Configuration

To unset individual keys:

$config = \Drupal::service('config.factory')->getEditable('system.performance');
$config->clear('cache.page.max_age')->save();
$page_cache_data = $config->get('cache.page');

This would return an array with one key “enabled” since “max_age” was cleared.

To delete entire configuration sets:

\Drupal::service('config.factory')->getEditable('system.performance')->delete();

Important: Do not call save() after delete(), or an empty config set will be created.

Best Practices

Avoid instantiating the same config object multiple times in one function:

\Drupal::service('config.factory')->getEditable('foo.bar')->set('foo', 'foo')->save();
\Drupal::service('config.factory')->getEditable('foo.bar')->set('bar', 'bar')->save();

Instead, instantiate once and reuse:

$config = \Drupal::service('config.factory')->getEditable('foo.bar');
$config
  ->set('foo', 'foo')
  ->set('bar', 'bar')
  ->save();

Injecting Configuration Values into Services

To inject config values into custom services using a service factory:

services:
  app.service:
    class: Drupal/mail_module/Service
    factory: Drupal/mail_module/ServiceFactory:create
    arguments: ['@config.factory']

class ServiceFactory {
  static function create($config) {
    return new Service($config->get('mail.config')->get('transport'));
  }
}

class Service {
  public function __construct($transport) {
    $this->mailTransport = $transport;
  }
}

Example adapted from How to inject configuration values into services?