Definition und Verwendung Ihrer eigenen Konfiguration in Drupal 8

Hauptthema: Eigene Konfiguration definieren

Sie können Standardkonfiguration in Ihr Modul einbinden, basierend auf der Funktionalität anderer Module (Content-Typen, Views, Felder, Textformate usw.).
Beispielsweise stellt das Node-Modul die Konfiguration des Inhaltstyps bereit, sodass Sie in Ihrem eigenen Modul den Standard-Inhaltstyp konfigurieren können, der mit Ihrem Modul geliefert wird.

Eventuell möchten Sie Konfiguration für eigene Plugins, Entitäten und Einstellungen definieren, die wiederum von anderen Modulen verwendet werden können, so wie Sie die Konfiguration des Inhaltstyps eines Nodes verwenden können. Drupal 8 erleichtert es, Ihren Teil der Konfiguration zu definieren.

Konfigurationsdatei

Konfigurationsdateien für Ihr Modul befinden sich im Unterverzeichnis config/install Ihres Moduls. Also z. B. /modules/example/config/install/example.settings.yml, wenn sich Ihr Modul in /modules/example befindet. Hier können Sie Konfigurationsdateien für Ihr Modul im YAML-Format ablegen.

Obwohl es nicht zwingend vorgeschrieben ist, wird dringend empfohlen, die von Ihnen definierten Konfigurationsdateien mit dem Präfix Ihres Modulnamens zu benennen: example.settings.yml z. B. für Konfigurationseinstellungen. Benennen Sie die Datei nicht settings.yml oder system.settings.yml, da dies zu Konflikten mit Dateien an anderen Stellen führen kann. Wenn Sie diese Konvention nicht einhalten, kann Drush bei Befehlen wie drush config:import verwirrt werden.

Dies erlaubt Ihnen auch, Konfigurationen für andere Komponenten bereitzustellen, z. B. ein Beispiel für einen Inhaltstyp, indem Sie Standardkonfiguration in Ihr Modul einbinden, bei dem die Konfigurationsdatei node.type.example_mytype.yml heißt und von dem Node-Modul als Inhaltstyp erkannt wird.

Der Dateiname der Konfigurationsdatei (ohne die .yml-Erweiterung) wird auch als Konfigurationsname im System bezeichnet, und so können Sie Ihre Konfiguration über das PHP-API ansprechen.

Struktur der Konfigurationsdatei

Die Konfigurationsdatei muss im YAML-Format vorliegen. Sie können die Struktur Ihrer eigenen Konfigurationsdatei frei gestalten, solange sie gültiges YAML ist. Beispielsweise, wenn Sie eine Einstellung für eine spezielle Ausgabe in Ihrem Seitencontroller benötigen, könnte die Datei einen Schlüssel message mit einem String-Wert enthalten:

message: 'Hello'
langcode: 'en'

Es wird empfohlen, den Sprachcode der Datei unter dem Schlüssel langcode zu speichern. Dieser wird vom Sprachsystem verwendet, um übersetzbaren Text für Übersetzungen bereitzustellen. Der Schlüssel langcode ist für diesen Zweck reserviert und sollte nicht für andere Zwecke auf oberster Ebene der Datei genutzt werden.

Um Konfigurationen übersetzbar zu machen, muss das Configuration Translation-Modul aktiviert sein.

Um die Konfiguration übersetzbar zu machen, müssen Sie zwei weitere Dateien hinzufügen:

- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml

Die erste definiert ein Schema für Ihre benutzerdefinierte Konfiguration. Wir definieren example.settings als config_object, das mehrere Felder enthält. Jedes Feld hat einen Typ: die Definition des Basistyps bestimmt, ob das Feld übersetzbar ist oder nicht (siehe core.data_types.schema.yml). Zum Beispiel ist path (ein interner Drupal-Pfad) nicht übersetzbar, text hingegen schon.

# /modules/example/config/schema/example.schema.yml
example.settings:
  type: config_object
  label: 'Example config'
  mapping:
    message:
      type: text
      label: 'Message'

Die zweite Datei fügt einen Link zur Übersetzungsseite /admin/config/regional/config-translation für das entsprechende Übersetzungsformular hinzu:

# /modules/example/example.config_translation.yml
example.admin.config:
  title: 'Example module'
  base_route_name: example.admin.config
  names:
    - example.settings

Konventionell stimmt der Schlüssel mit dem Basis-Routennamen überein: example.admin.config ist der Name der Route zum Administrationsformular Ihres Moduls. Die names-Liste führt alle Konfigurationsschlüssel auf, die im Formular bearbeitet werden, in diesem Fall die benutzerdefinierte Konfiguration, die oben im Schema definiert wurde.

Die Datei kann komplexere Listen und Schlüssel-Wert-Paare in einer Baumstruktur enthalten. Siehe z. B. die Datei views.view.content.yml für ein Beispiel einer etwas komplexeren Konfigurationsdatei.

Die Konfigurationsübersetzung fügt automatisch einen Tab „Modulübersetzung“ zum Konfigurationsformular des Moduls hinzu, der aber eventuell nicht angezeigt wird, wenn dies der einzige verfügbare Tab ist. Um einen „Standard“-Tab für das Konfigurationsformular hinzuzufügen, müssen wir eine weitere Datei example.links.task.yml hinzufügen. (Siehe Vom Modul definierte lokale Aufgaben.)

# example.links.task.yml
example.admin.config:
  route_name: example.admin.config
  title: Settings
  base_route: example.admin.config

Verwendung der Konfiguration

Drupal 8 stellt ein PHP-API zum Lesen und Schreiben dieser Konfiguration bereit. Der einfachste Weg, dies zu nutzen, ist die statische Methode Drupal::config():

$config = \Drupal::config('example.settings');
// Gibt 'Hello' aus.
print $config->get('message');
// Gibt 'en' aus.
print $config->get('langcode');

Wenn Sie die Konfiguration bearbeiten und mit einem neuen Wert aktualisieren möchten, können Sie den Dienst \Drupal::service('config.factory')->getEditable() verwenden:

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

// Setzt und speichert den neuen Wert für message.
$config->set('message', 'Hi')->save();

// Gibt nun 'Hi' aus.
print $config->get('message');

Siehe auch

• Configuration API in Drupal 8