API für einfache Konfiguration

Auf dieser Seite wird die API beschrieben, mit der Sie Konfigurationsdaten für einfache Konfigurationen abrufen und einstellen können. (Dies betrifft nicht die in Konfigurationsobjekten gespeicherten Informationen.)

Konfigurationsdaten

Jedes Modul kann Standardkonfigurationen bereitstellen. Beispielsweise sind die Wartungsmodus-Einstellungen in core/modules/system/config/install/system.maintenance.yml definiert. In dieser Datei ist der erste Teil der Namespace, der angibt, welches Modul diese Konfiguration bereitstellt (im Beispiel das Systemmodul), gefolgt von der Subsystembezeichnung (hier Wartung). Die Datei muss im Verzeichnis config/install liegen. Außerdem muss sie im Dateinamen einen Punkt enthalten, um die Prüfung in ConfigBase->validateName($name) zu bestehen. Die Datei enthält folgendes YAML:

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

Konfigurationen können auch verschachtelt sein, wie z. B. bei den Performance-Einstellungen (system.performance.yml):

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

WICHTIG: Root-Schlüssel müssen ein Mapping (Assoziatives Array) sein

Daten an der Wurzel der Konfiguration müssen als Mapping und nicht als unvorhersehbare Sequenz dargestellt werden. Wenn Sie z. B. Daten für jeden verfügbaren Entity-Typ speichern, verwenden Sie den übergeordneten Schlüssel als Entity-Typ und fügen den Root-Schlüssel entity_type hinzu. Siehe folgendes Layout-Beispiel:

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

Wenn Entity-Typen als Root-Schlüssel verwendet werden, kann die Konfiguration nicht mit einer Schema beschrieben werden. Außerdem kann der Drupal-Core keine zusätzlichen Informationen hinzufügen, wenn die Konfiguration als Teil einer Modul- (oder Theme-) Installation gesetzt wird.

Interaktion mit der Konfiguration

Sie interagieren mit diesen Dateien über ein Config-Objekt, das Sie erstellen, indem Sie die Funktion config() mit dem Dateinamen ohne Erweiterung aufrufen. Der Aufruf von config liefert eine Instanz von \Drupal\Core\Config\ImmutableConfig zurück.

// Immutable Config (Nur Lesen).
$config = \Drupal::config('system.performance');

// Mutable Config (Lesen / Schreiben).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Nachdem Sie das Config-Objekt erhalten haben, können Sie unterschiedlich mit ihm arbeiten.

Konfiguration lesen

Konfiguration wird mit der Methode get() gelesen. Dies kann auf verschiedene Arten geschehen. Um einen Konfigurationsabschnitt zu lesen, geben Sie einfach seinen Schlüssel an.

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

Aufrufe von \Drupal::config() können auch verkettet werden.

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

Um verschachtelte Konfigurationen zu lesen, trennen Sie die Schlüssel mit dem Zeichen „.“.

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

Sie können die Konfiguration auf jeder Ebene lesen, solange unter der angegebenen Ebene eine Array-verschachtelte Konfiguration vorhanden ist.

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

Dies gibt ein Array mit zwei Schlüsseln zurück – „enabled“ und „max_age“.

Um alle Daten im Konfigurationsobjekt zurückzugeben, rufen Sie get() ohne Argumente auf.

Sie können auch alle in der Konfiguration verfügbaren Schlüssel oder nur die, die mit einer bestimmten Teilzeichenkette (Prefix $) beginnen, zurückgeben.

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

Konfiguration schreiben

Um Konfiguration zu ändern, müssen Sie eine Instanz von \Drupal\Core\Config\Config (editierbares Konfigurationsobjekt) erhalten, indem Sie getEditable() auf der Config-Fabrik aufrufen. Ein Versuch, eine Änderung vorzunehmen oder die Methoden delete() / save() auf einer Instanz von \Drupal\Core\Config\ImmutableConfig aufzurufen, löst eine Ausnahme ImmutableConfigException aus.

Dies erfolgt wie folgt:

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

Konfiguration wird mit der Methode set() geändert oder hinzugefügt und mit save() gespeichert. Beachten Sie, dass Konfiguration explizit gespeichert werden muss; einfaches Setzen von Daten in die Konfiguration speichert diese nicht automatisch.

Sie speichern Daten im Konfigurationsobjekt genauso, wie Sie diese lesen, indem Sie auf Schlüssel verweisen und die entsprechenden Werte setzen. Die Syntax ist dieselbe wie bei variable_set(), das in früheren Drupal-Versionen verwendet wurde.

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

// Setze einen Skalarwert.
$config->set('cache.page.enabled', 1);

// Setze ein Array von Werten.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Speichere die Daten in der Datenbank.
$config->save();

Die set()-Methode ist auch verkettbar, sodass Sie, wenn Sie nur einen Wert ändern möchten, dies in einer einzigen Codezeile tun können.

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

Wenn Sie alle Daten im Konfigurationsobjekt ersetzen möchten, verwenden Sie die Methode setData(). Sie können setData() nicht verwenden, um nur einen Teil der Daten zu ersetzen – wenn Sie weniger als das ganze Objekt ersetzen wollen, müssen Sie stattdessen einen oder mehrere set()-Aufrufe verwenden. Beim Verwenden von setData() müssen Sie jeden Schlüssel und Wert im selben Format eines assoziativen Arrays angeben, wie es get() ohne Argumente zurückgibt. Für die System-Performance-Parameter in system.performance.yml sieht das wie folgt aus:

// Alle Werte setzen.
\Drupal::service('config.factory')->getEditable('system.performance')->setData([
    'cache' => [
      'page' => [
        'enabled' => '0',
        'max_age' => '0',
      ],
    ],
    'preprocess' => [
      'css' => '0',
      'js' => '0',
    ],
    'response' => [
      'gzip' => '0',
    ],
  ])
  ->save();

Konfiguration löschen

Einzelne Konfigurationswerte können mit der Methode clear() zurückgesetzt werden, welche ebenfalls verkettbar ist.

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

In diesem Beispiel gibt $page_cache_data ein Array mit nur einem Schlüssel „enabled“ zurück, da „max_age“ gelöscht wurde.

Gesamte Konfigurationssets können mit der Methode delete() entfernt werden.

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

Beachten Sie, dass danach kein save() aufgerufen werden sollte, da sonst eine leere Version des Konfigurationssets erzeugt wird.

Best Practices

Vermeiden Sie es, Instanzen von Konfigurationsobjekten mehrfach innerhalb derselben Funktion zu erstellen, da dies die Leistung beeinträchtigt. Der folgende Code erstellt das Konfigurationsobjekt 'foo.bar' unnötig zweimal.

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

Besser ist es, das Konfigurationsobjekt einmal zu erstellen, es in einer Variable zu speichern und dann mit dieser Variable im Rest Ihres Codes zu arbeiten.

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

Einfügen von Konfigurationswerten in Services

Konfigurationswerte können in Ihren benutzerdefinierten Service eingebracht werden, indem Sie die Service-Fabrik verwenden.

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

Das Beispiel wurde adaptiert von Wie man Konfigurationswerte in Services einfügt.