Konfigurationsüberschreibungssystem

Das Drupal-8-Konfigurationssystem behandelt Konfiguration einheitlich. Standardmäßig speichert Drupal Konfigurationsdaten in der Datenbank, aber diese können in YAML-Dateien exportiert werden, was die Verwaltung der Konfiguration mit Versionskontrolle ermöglicht. Es gibt jedoch Fälle, in denen Konfigurationswerte für bestimmte Zwecke überschrieben werden müssen. In Drupal 7 gab es die Variable global $conf, die üblicherweise in settings.php mit bedingten Überschreibungswerten für Konfiguration gefüllt wurde. Ein großer Nachteil dieses Systems war, dass Überschreibungen in die eigentliche Konfiguration übergingen. Wenn ein Konfigurationsformular mit überschriebenen Werten gespeichert wurde, gelangte die bedingte Überschreibung in den Speicher der tatsächlichen Konfiguration.

Drupal 8 führt ein Konfigurationsüberschreibungssystem ein, das:

• diese Überschreibungen als temporäre Schichten über den Standardkonfigurationswerten unterstützt,
• überschriebene Werte nicht für Konfigurationsformulare verwendet,
• Überschreibungen zusammen mit anderen Konfigurationsdateien speichern kann, um Deployment und Versionskontrolle zu unterstützen (z. B. bei Sprachüberschreibungen; siehe unten).

Die globale Variable $conf aus Drupal 7 wurde in Drupal 8 in $config umbenannt und im Standard-Konfigurationssystem aktiviert.

Globale Überschreibungen

Drupal 8 behält die Möglichkeit der Verwendung von global $config bei. Das Konfigurationssystem kombiniert diese Überschreibungswerte über die Implementierung von Drupal\Core\Config\ConfigFactory::get(). Wenn Sie einen Wert aus der Konfiguration abrufen, erhält die globale Variable $config die Möglichkeit, den zurückgegebenen Wert zu ändern:

// Systemwartungsnachricht abrufen. Dieser Wert kann standardmäßig
// durch global $config überschrieben werden (sowie durch Übersetzungen, siehe unten).
$message = \Drupal::config('system.maintenance')->get('message');

Um Konfigurationswerte in global $config zu überschreiben, zum Beispiel in settings.php, greifen Sie auf ihre Konfigurationsschlüssel zu:

$config['system.maintenance']['message'] = 'Entschuldigung, unsere Seite ist derzeit nicht erreichbar.';

Für verschachtelte Werte verwenden Sie verschachtelte Array-Schlüssel:

$config['system.performance']['css']['preprocess'] = 0;

Wenn Sie $config außerhalb der Datei settings.php verwenden, verwenden Sie das vorherige globale $config;

Es kann hilfreich sein, verfügbare Konfigurationsvariablen auf eine der folgenden Arten zu ermitteln:

• Sie mit dem Modul „Configuration Manager“ über die Benutzeroberfläche unter /admin/config/development/configuration/single/export ansehen,
• Ihre Site-YML-Konfigurationsdateien direkt überprüfen,
• oder sie mit Drush abfragen.

drush config-list
drush config-get system.performance --include-overridden

Beachten Sie, dass Werte, die mit $config in settings.php überschrieben wurden, nicht über die Drupal-Administrationsoberfläche sichtbar sind (bis #2408549: In Konfigurationsformularen werden keine überschriebenen Werte angezeigt, oder Sie verwenden Module wie Configuration Override Warn oder Config Override Inspector) oder bei Drush-Abfragen (wenn Sie nicht den Schalter --include-overridden hinzufügen). Die Admin-Oberfläche zeigt die gespeicherten Konfigurationswerte an, sodass Änderungen an anderen Umgebungen vorgenommen werden können, die keine Überschreibungen haben.

Ein Beispiel für das Überschreiben von API-Schlüsseln aus Sicherheitsgründen finden Sie unter: Commerce Gateway Payment API-Schlüssel überschreiben

Überschreibungen vermeiden

Sie können die Konfiguration auch ohne Überschreibungen abrufen, um auf den rohen Konfigurationswert zuzugreifen (zum Beispiel, um die Anwendung selbst globaler Überschreibungen zu deaktivieren). Das ist besonders nützlich, wenn Sie ein Konfigurationsformular schreiben. Es ist wichtig, für das Formular eine überschreibungsfreie Umgebung zu verwenden, um zu vermeiden, dass Werte in die gespeicherte Konfiguration gelangen. Besonders relevant ist das, wenn Ihr Code in einer mehrsprachigen Umgebung verwendet wird, in der Konfigurationswerte üblicherweise als Übersetzungen überschrieben werden.

Hier einige Beispiele für das Abrufen von Konfiguration mit und ohne Überschreibungen:

// Site-Name mit Überschreibungen abrufen.
$site_name = \Drupal::config('system.site')->get('name');

// Site-Name ohne Überschreibungen abrufen.
$site_name = \Drupal::config('system.site')->getOriginal('name', FALSE);
// Beachten Sie, dass mutable config immer ohne Überschreibungen ist.
$site_name = \Drupal::configFactory()->getEditable('system.site')->get('name');

Sie können auch direkt auf den Speicherdienst config.storage zugreifen, der StorageInterface::read() implementiert. Dies ist jedoch selten der richtige Weg, um auf Konfiguration zuzugreifen.

Sprachbezogene Überschreibungen

Beispielsweise muss beim Versenden einer E-Mail an einen Benutzer dessen Konfiguration in der Sprache des Benutzers und nicht der Seite vorliegen. Merken Sie sich die zuvor verwendete Sprache, stellen Sie die korrekte Sprache je nach Benutzer ein, führen Sie die konfigurationsbasierten Operationen aus und setzen Sie die Sprache zurück:

// Sprachmanager-Dienst laden
$language_manager = \Drupal::service('language_manager');

// Zielsprachobjekt abrufen
$langcode = $account->getPreferredLangcode();
$language = $language_manager->getLanguage($langcode);

// Ursprüngliche Sprache vor der Operation merken.
$original_language = $language_manager->getConfigOverrideLanguage();
// Übersetzungs-Zielsprache in der Konfigurationsfabrik setzen.
$language_manager->setConfigOverrideLanguage($language);

$mail_config  = \Drupal::config('user.mail');

// Jetzt E-Mail basierend auf $mail_config senden, die in der richtigen Sprache ist.

// Konfigurationssprache zurücksetzen.
$language_manager->setConfigOverrideLanguage($original_language);

Das Sprachüberschreibungssystem verwendet ebenfalls den Konfigurationsspeicher zur Ablage von Überschreibungen (im Gegensatz zu globalen $config-basierten Überschreibungen). Sprachüberschreibungen werden in Dateien gespeichert, die nach ihrer Basisdatei benannt sind. Wenn also für die oben genannte Konfigurationsdatei user.mail eine Überschreibung für eine bestimmte Sprache existiert, heißt diese language.config.$langcode.user.mail. Die Überschreibungsdateien werden mit dem Präfix language.config. gefolgt vom Sprachcode und dann dem ursprünglichen Konfigurationsschlüssel benannt. Das Ablegen der Dateien neben der regulären Konfiguration unterstützt schrittweise Übersetzung der Konfiguration und kann wie die Basis-Konfiguration verändert werden.

Wie werden diese Sprachüberschreibungsdateien ursprünglich erstellt? Das Locale-Modul integriert sich mit Systemereignissen, um Übersetzungsdateien für bereitgestellte Konfiguration basierend auf der Konfigurationsschemainformation zu generieren. Es gibt auch das Core-Modul Config Translation, das eine Benutzeroberfläche zur Übersetzung von Konfiguration basierend auf der Schema bietet. Es funktioniert sowohl mit bereitgestellter als auch benutzerdefinierter Konfiguration und nutzt dieselben Sprachüberschreibungsdateien.

Bereitstellung von Überschreibungen durch Module

Es ist auch möglich, Modulumfang-Überschreibungen aus jedem Modul bereitzustellen. Obwohl Drupal Core globale und sprachbasierte Überschreibungen unterstützt, gibt es Anwendungsfälle für viele weitere Arten von Überschreibungen, einschließlich rollenbasierten, kontextbezogenen, domänenbasierten, gruppenbasierten usw. Module können ihre eigenen Kriterien für diese Überschreibungen definieren.

Wenn die ConfigFactory modulübergreifende Überschreibungen sammelt, ruft sie alle Dienste mit dem Tag config.factory.override auf:

config_example.services.yml

services:
  config_example.overrider:
    class: Drupal\config_example\Config\ConfigExampleOverrides
    tags:
      - { name: config.factory.override, priority: 5 }

Setzen Sie die Priorität des Subscribers, um die Priorität der Überschreibungen anzugeben. Überschreibungen mit höherer Priorität haben Vorrang vor solchen mit niedrigerer Priorität (bei gleichem Konfigurationsnamen).

src/Config/ConfigExampleOverrides.php

namespace Drupal\config_example\Config;

use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Config\ConfigFactoryOverrideInterface;
use Drupal\Core\Config\StorageInterface;

/**
 * Beispiel für eine Konfigurationsüberschreibung.
 */
class ConfigExampleOverrides implements ConfigFactoryOverrideInterface {

  /**
   * {@inheritdoc}
   */
  public function loadOverrides($names) {
    $overrides = array();
    if (in_array('system.site', $names)) {
      $overrides['system.site'] = ['name' => 'Überschriebener Seitenname!'];
    }
    return $overrides;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheSuffix() {
    return 'ConfigExampleOverrider';
  }
  
  /**
   * {@inheritdoc}
   */
  public function getCacheableMetadata($name) {
    return new CacheableMetadata();
  }

  /**
   * {@inheritdoc}
   */
  public function createConfigObject($name, $collection = StorageInterface::DEFAULT_COLLECTION) {
    return NULL;
  }

}

Konfigurationsüberschreibungen funktionieren auf drei Ebenen: Sprache, Module und settings.php, wobei letztere Vorrang hat. Überschreibungen in settings.php haben Vorrang vor Werten, die von Modulen bereitgestellt werden. Modulüberschreibungen haben Vorrang vor sprachbezogenen Überschreibungen. Die Priorität des Ereignis-Subscribers für Modulüberschreibungen legt nur die Priorität im Vergleich zu anderen Modulüberschreibungen fest, nicht gegenüber Sprach- oder settings.php-Überschreibungen.

Beachten Sie, dass Konfigurationsformulare in Drupal Core keine überschriebenen Konfigurationswerte verwenden. Im obigen Beispiel einer Modulüberschreibung sehen Sie „Überschriebener Seitenname!“ nicht in /admin/config/system/site-information.

Es lohnt sich, noch einmal zu betonen, dass wenn Sie die ursprünglichen Konfigurationswerte in einer Überschreibung lesen müssen, z. B. zum Vergleichen oder Zusammenführen, Sie diese aus \Drupal::configFactory und nicht aus \Drupal::config laden sollten, um einen verschachtelten Zyklus in Ihrer Überschreibung zu vermeiden:

$original = \Drupal::configFactory()->getEditable('system.site')->getOriginal('name', FALSE);

Weitere Referenzen

Das Überschreibungssystem in seiner letzten/aktuellen Form wurde in #2098119: Ersetzen des Config-Kontextsystems mit eingebauter Locale- und Event-basierter Überschreibung eingeführt.

Historische/veraltete Informationen finden Sie in #1646580: Implementierung von Config Events und Listenern für lokalisierte Konfiguration und Überschreibungsbereiche sowie #1763640: Einführung von Config Context zur Verfügbarkeit von Originalkonfiguration und anderen Überschreibungen und weiteren Überschreibungen mit kontextbezogenem Zugriff. Sprachbezogene Überschreibungen wurden später in #2020361: Erstellung von LanguageConfigContext zur Aktivierung sprachbasierter Konfigurationsüberschreibungen hinzugefügt.