API de configuration simple

Cette page décrit l’API pour accéder et configurer des données de configuration simple. (Ce n’est pas pour les informations stockées dans les objets de configuration.)

Données de configuration

Chaque module peut fournir une configuration par défaut. Par exemple, les réglages du mode maintenance sont définis dans core/modules/system/config/install/system.maintenance.yml. Dans ce fichier, la première partie représente l’espace de noms, indiquant quel module fournit cette configuration (ici le module système), suivi par la sous-système (ici maintenance). Le fichier doit être situé dans le dossier config/install. Il doit aussi contenir un point « . » dans son nom, vérifié par ConfigBase->validateName($name). Ce fichier contient le YAML suivant :

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

La configuration peut aussi être imbriquée, comme dans les réglages de performance (system.performance.yml) :

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

IMPORTANT : les clés racines doivent être un tableau associatif

Les données à la racine doivent être un tableau associatif, pas une liste ordonnée imprévisible. Par exemple, si vous stockez des données par type d’entité, faites de la clé parente le type d’entité et utilisez un clé racine entity_type. Exemple :

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

Si les types d’entités sont la clé racine, il n’est pas possible de représenter cette configuration via une schéma. De plus, le core Drupal ne pourra pas ajouter d’informations supplémentaires quand la configuration est installée via un module ou un thème.

Interaction avec la configuration

Vous interagissez avec ces fichiers via un objet Config. Vous créez une instance Config en appelant la fonction config() avec le nom du fichier sans extension. Cette fonction retourne une instance de \Drupal\Core\Config\ImmutableConfig.

// Config immutable (lecture seule).
$config = \Drupal::config('system.performance');

// Config mutable (lecture / écriture).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Une fois l’objet Config obtenu, vous pouvez interagir de plusieurs manières.

Lecture de la configuration

La configuration se lit via la méthode get(). Vous pouvez lire un fragment de configuration en précisant simplement la clé :

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

Les appels à \Drupal::config() peuvent aussi être chaînés :

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

Pour lire une configuration imbriquée, séparez les clés par un point « . » :

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

Vous pouvez lire la configuration à n’importe quel niveau si un tableau est imbriqué :

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

Cela retourne un tableau avec les clés « enabled » et « max_age ».

Pour récupérer toutes les données de l’objet configuration, appelez get() sans argument.

Vous pouvez aussi lister toutes les clés de configuration disponibles dans le système, ou seulement celles commençant par un certain préfixe :

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

Écriture de la configuration

Pour modifier la configuration, vous devez obtenir une instance mutable \Drupal\Core\Config\Config via getEditable() de la factory. Tenter de modifier ou d’appeler delete()/save() sur une instance ImmutableConfig déclenche une exception ImmutableConfigException.

Exemple :

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

Modifiez ou ajoutez via set(), puis sauvegardez avec save(). Notez que la configuration doit être explicitement sauvegardée ; set() seul ne persiste pas les modifications.

Vous modifiez la configuration en ciblant les clés et leurs valeurs, même syntaxe que l’ancienne fonction variable_set() :

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

// Définir une valeur scalaire.
$config->set('cache.page.enabled', 1);

// Définir un tableau de valeurs.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Sauvegarder les données dans la base.
$config->save();

La méthode set() est chaînable, donc pour changer une seule valeur :

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

Pour remplacer toutes les données de l’objet configuration, utilisez setData(). Vous ne pouvez pas remplacer un sous-ensemble avec setData(), dans ce cas utilisez set() pour chaque clé. setData() attend un tableau associatif complet, comme celui retourné par get() sans argument. Exemple pour system.performance.yml :

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

Suppression de configuration

Les valeurs individuelles peuvent être effacées via clear(), qui est chaînable :

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

Ici, $page_cache_data retournera un tableau ne contenant que « enabled », puisque « max_age » a été supprimé.

Pour supprimer un ensemble complet de configuration, utilisez delete() :

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

Notez qu’il ne faut pas appeler save() après delete(), cela recréerait une configuration vide.

Bonnes pratiques

Évitez de créer plusieurs instances d’un même objet configuration dans la même fonction, cela dégrade les performances. Le code suivant crée inutilement deux fois l’objet 'foo.bar' :

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

Mieux vaut créer l’objet une fois, le stocker dans une variable et travailler dessus :

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

Injection de valeurs de configuration dans les services

Vous pouvez injecter des valeurs de configuration dans vos services personnalisés via une factory de service :

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;
  }
}

L’exemple est adapté de Comment injecter des valeurs de configuration dans les services ?