Définir et utiliser votre propre configuration dans Drupal 8
Sujet principal : définition de votre propre configuration
Vous pouvez inclure la configuration par défaut dans votre module, en vous basant sur les fonctionnalités d’autres modules (types de contenu, vues, champs, formats de texte, etc.).
Par exemple, le module de contenu fournit la configuration d’un type de contenu, ainsi dans votre propre module vous configurez un type de contenu par défaut qui peut être livré avec votre module.
Il se peut que vous souhaitiez définir une configuration pour vos propres plugins, entités et réglages, qui peuvent ensuite être utilisés par d’autres modules, tout comme vous pouvez utiliser la configuration du type de contenu d’un nœud. Drupal 8 facilite la définition de votre partie de configuration.
Fichier de configuration
Les fichiers de configuration de votre module se trouvent dans le sous-répertoire config/install de votre module. Ainsi, /modules/example/config/install/example.settings.yml, si votre module se trouve dans /modules/example. Vous pouvez placer ici les fichiers de configuration de votre module, en utilisant le format YAML.
Bien que ce ne soit pas obligatoire, il est fortement recommandé de nommer les fichiers de configuration que vous définissez pour votre module en utilisant le préfixe du nom de votre propre module : example.settings.yml, par exemple pour les paramètres de configuration. Ne nommez pas un fichier settings.yml ou system.settings.yml, car cela pourrait entrer en conflit avec les noms de fichiers ailleurs. Si vous ne suivez pas cette convention, les commandes Drush telles que drush config:import seront confuses.
Cela vous permet également de fournir la configuration pour d’autres composants, par exemple un type de contenu d’exemple, incluant la configuration par défaut dans votre module, où le fichier de configuration était node.type.example_mytype.yml, identifiant le fichier de configuration qui sera traité comme un type de contenu par le module node.
Le nom du fichier de configuration (à l’exception de l’extension .yml) est aussi appelé nom de configuration dans le système, et c’est ainsi que vous pouvez accéder à votre configuration via l’API PHP.
Structure du fichier de configuration
Le fichier de configuration doit utiliser le format YAML. Vous pouvez structurer votre propre fichier de configuration selon vos besoins, il n’y a pas de restrictions excepté le format YAML lui-même pour la structure. Par exemple, si vous avez besoin d’un paramètre pour afficher quelque chose de particulier depuis votre contrôleur de page, le fichier peut contenir une clé message avec une valeur de type chaîne :
message: 'Hello' langcode: 'en'
Il est recommandé d’inclure le code langue du fichier sous la clé langcode. Cela est utilisé par le système de langues pour proposer un texte traduisible. La clé langcode est réservée à cet usage et vous ne devez pas l’utiliser au niveau supérieur du fichier pour autre chose.
Pour la traduction de la configuration, le module de traduction de configuration doit être activé.
Pour rendre la configuration traduisible, vous devez ajouter deux fichiers supplémentaires :
- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml
Le premier définit la schéma de la configuration personnalisée. Nous définirons example.settings comme un objet config_object, contenant plusieurs champs. Chaque champ a un type : la définition du type de base détermine si le champ est traduisible ou non (voir core.data_types.schema.yml). Par exemple, path, qui contient un chemin interne Drupal, n’est pas traduisible, tandis que text l’est.
# /modules/example/config/schema/example.schema.yml
example.settings:
type: config_object
label: 'Example config'
mapping:
message:
type: text
label: 'Message'
Le second ajoute un lien vers /admin/config/regional/config-translation dans le formulaire de traduction correspondant :
# /modules/example/example.config_translation.yml
example.admin.config:
title: 'Example module'
base_route_name: example.admin.config
names:
- example.settings
Par convention, la clé correspond au nom de la route de base : example.admin.config est le nom de la route vers le formulaire de configuration administrateur de votre module. Les noms listent toutes les clés de configuration éditées dans le formulaire, ici la configuration personnalisée définie dans le schéma ci-dessus.
Le fichier peut inclure des listes plus complexes et des paires clé/valeur en structure arborescente. Voir par exemple le fichier views.view.content.yml pour un exemple de fichier de configuration avec un peu plus de complexité.
La traduction de la configuration ajoute automatiquement un onglet « module de traduction » dans le formulaire de configuration du module, toutefois il peut ne pas s’afficher si c’est le seul onglet disponible. Pour ajouter un onglet « par défaut » au formulaire de configuration, il faut ajouter un autre fichier example.links.task.yml. (Voir Les tâches locales définies par un module.)
# example.links.task.yml example.admin.config: route_name: example.admin.config title: Settings base_route: example.admin.config
Utilisation de la configuration
Drupal 8 fournit une API PHP pour lire et écrire cette configuration. La manière la plus simple de l’utiliser est la méthode statique Drupal::config() :
$config = \Drupal::config('example.settings');
// Affichera 'Hello'.
print $config->get('message');
// Affichera 'en'.
print $config->get('langcode');
Si vous souhaitez éditer la configuration et la mettre à jour avec une nouvelle valeur, vous pouvez utiliser la méthode \Drupal::service('config.factory')->getEditable() :
$config = \Drupal::service('config.factory')->getEditable('example.settings');
// Définir et sauvegarder une nouvelle valeur pour message.
$config->set('message', 'Hi')->save();
// Maintenant affichera 'Hi'.
print $config->get('message');