Now that we have talked about what the Drupal 8 configuration API is, what is it used for, how is it managed and stored, and what are some of the options for overriding it, it's time to talk about the API itself and how we can interact with it. In this section, we will focus only on simple configuration as we will talk more about configuration entities when we cover all entities.
In Chapter 2, Creating Your First Module, we already became somewhat exposed to the configuration API in our SalutationConfigurationForm where we stored and read a simple configuration value. Now it's time to go a bit deeper to understand the API and look at some more examples of how we can use it.
The class that represents simple configuration is Drupal\Core\Config and it wraps around the data found in one individual configuration item. Moreover, it does all the necessary in terms of interacting with the underlying storage system in order to persist the configuration (by default into the database). In addition, it handles the overrides we talked about earlier automatically.
An important subclass of Config that we work with a lot is ImmutableConfig. Its purpose is to prevent changes being made to the configuration object, and as such, it is for read-only uses.
The way we get to use instances of these classes is through the ConfigFactory service which has two handy methods for getting a configuration object:
/** @var \Drupal\Core\Config\ConfigFactoryInterface $factory */
$factory = \Drupal::service('config.factory');
$read_only_config = $factory->get('hello_world.custom_salutation');
$read_and_write_config = $factory->getEditable('hello_world.custom_salutation');
The get() method returns an ImmutableConfig object that is read-only, while the getEditable() method returns a Config object that can be used also for changing the configuration values. The way we do this is via the set() and save() methods:
$read_and_write_config->set('salutation', 'Another salutation');
$read_and_write_config->save();
Very simple. We also have the setData() method which allows us to change the entire data of the configuration item at once. As a parameter, it expects an associative array of values.
To read the data, we have a number of options. We can read one element from the config:
$value = $read_and_write_config->get('salutation');
If the element is nested, we can traverse down via the dot (.) notation:
$config = $factory->get('system.site');
$value = $config->get('page.403');
This will return the value set for the 403 page in the system.site configuration. We can also get all the values by simply not passing any parameters to the get() method, which would return an associative array.
If you remember our discussion about the configuration overrides, by default, the get() method will return the values as they had been overridden through the module or globally (or as a language if the language manager has a different language set for configuration). However, if we want, we can also retrieve the original value:
$config = $factory->get('system.maintenance');
$value = $config->getOriginal('message', FALSE);
The second parameter of getOriginal() indicates whether to apply overrides and, by default, it is TRUE. So this way, we get the configuration value that is set in the active storage.
Finally, we can also clear configuration values or the entire objects themselves. For example, consider the following code:
$config->clear('message')->save();
It will remove the message key from the configuration object and save it without that value. Alternatively, we can also remove the entire thing:
$config->delete();
That is pretty much it. The power of this API also stems from its simplicity.