API voor eenvoudige configuratie

Op deze pagina wordt de API beschreven voor het ophalen en instellen van configuratiegegevens voor eenvoudige configuratie. (Dit geldt niet voor informatie die is opgeslagen in configuratieobjecten.)

Configuratiegegevens

Elke module kan standaardconfiguratie leveren. Bijvoorbeeld, de onderhoudsmodusinstellingen zijn gedefinieerd in core/modules/system/config/install/system.maintenance.yml. In dit bestand vormt het eerste deel een namespace die aangeeft welke module deze configuratie heeft geleverd (system module in dit voorbeeld), gevolgd door de subsysteemnaam (maintenance in dit voorbeeld). Het bestand moet zich in de map config/install bevinden. Het moet ook een “.” bevatten in de bestandsnaam voor de validatie in ConfigBase->validateName($name). Dit bestand bevat de volgende YAML:

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

Configuratie kan ook genest zijn, zoals in de prestatie-instellingen (system.performance.yml):

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

BELANGRIJK: root-keys moeten een mapping zijn

Gegevens op rootniveau van de configuratie moeten worden weergegeven als een mapping, niet als een onvoorspelbare sequentie. Bijvoorbeeld, als u gegevens wilt opslaan voor elk beschikbaar entiteitstype, gebruik dan het entiteitstype als bovenliggende sleutel en voeg een root-key entity_type toe. Zie het voorbeeld hieronder:

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

Als entiteitstypen de root-key zijn, is het onmogelijk om de configuratie te beschrijven met behulp van een schema. Bovendien kan de Drupal-core geen extra informatie toevoegen wanneer de configuratie wordt ingesteld als onderdeel van de installatie van een module (of thema).

Interactie met configuratie

U werkt met deze bestanden via het Config-object en maakt een instantie van het Config-object door de functie config() aan te roepen met de bestandsnaam minus de extensie. Het aanroepen van de config-functie retourneert een instantie van \Drupal\Core\Config\ImmutableConfig.

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

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

Nadat u een Config-object hebt, kunt u er op verschillende manieren mee werken.

Configuratie lezen

Configuratie wordt gelezen met behulp van de methode get(). Dit kan op meerdere manieren worden gebruikt. Om een configuratiestuk te lezen, specificeert u eenvoudig de sleutel.

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

Aanroepen van \Drupal::config() kunnen ook worden gekoppeld.

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

Om geneste configuratie te lezen, scheidt u de sleutels met een “.”-teken.

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

U kunt configuratie op elk niveau lezen, zolang er onderliggend configuratie in een array is genest.

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

Dit retourneert een array met twee sleutels - “enabled” en “max_age”.

Om alle gegevens in een configuratieobject te retourneren, roept u gewoon get() aan zonder argumenten.

U kunt ook alle configuratiesleutels die beschikbaar zijn in het systeem retourneren, of alleen die welke beginnen met een bepaalde substring (prefix $).

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

Configuratie schrijven

Om configuratie te wijzigen, moet u een instantie verkrijgen van \Drupal\Core\Config\Config (een aanpasbaar configuratieobject), door getEditable() aan te roepen op de configuratiefabriek. Een poging om wijzigingen aan te brengen of de functies delete() / save() aan te roepen op een instantie van \Drupal\Core\Config\ImmutableConfig resulteert in een ImmutableConfigException.

Dit doet u als volgt:

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

Configuratie wordt gewijzigd of toegevoegd met de methode set() en opgeslagen met de methode save(). Let op: configuratie moet expliciet worden opgeslagen; simpelweg gegevens instellen in de configuratie slaat deze niet op.

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

// Stel een scalair waarde in.
$config->set('cache.page.enabled', 1);

// Stel een array van waarden in.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Sla de gegevens op in de database.
$config->save();

De functie set() is ook chainable, dus als u slechts één waarde moet wijzigen, kunt u dit in één regel code doen.

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

Als u alle gegevens in een configuratieobject wilt vervangen, gebruik dan de functie setData(). U kunt setData() niet gebruiken om slechts een subset te vervangen – als u minder dan het volledige object wilt vervangen, moet u in plaats daarvan één of meerdere aanroepen van set() gebruiken. Bij gebruik van setData() moet u elke sleutel en waarde specificeren in hetzelfde associatieve arrayformaat dat wordt geretourneerd door get() zonder argumenten. Voor de systeem-prestatie-instellingen in system.performance.yml ziet dit er als volgt uit:

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

Configuratie verwijderen

Individuele configuratiewaarden kunnen worden gewist met de functie clear(), die ook chainable is.

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

In dit voorbeeld zal $page_cache_data een array retourneren met één sleutel - “enabled” - omdat “max_age” is verwijderd.

Hele configuratiesets kunnen worden verwijderd met de functie delete().

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

Let op: hierna moet u geen save() aanroepen, omdat dit een lege versie van de configuratieset zou creëren.

Best practices

Vermijd het meerdere keren aanmaken van configuratieobjecten binnen dezelfde functie, omdat dit tot prestatieverlies leidt. De volgende code maakt onnodig twee keer een instantie van het configuratieobject 'foo.bar'.

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

Een betere oplossing zou zijn om één keer een instantie van het configuratieobject te maken, deze in een variabele op te slaan en met die variabele te werken voor de rest van uw code.

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

Injectie van configuratiewaarden in services

Configuratiewaarden kunnen in uw custom service worden geïnjecteerd met behulp van een servicefactory.

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

Het voorbeeld is aangepast van Hoe configuratiewaarden in services te injecteren?