Configuratie-override systeem

Het configuratiesysteem van Drupal 8 verwerkt configuratie op een uniforme manier. Standaard slaat Drupal configuratiegegevens op in de database, maar ze kunnen worden geëxporteerd naar YAML-bestanden, wat versiebeheer mogelijk maakt. Er zijn echter gevallen waarin configuratiewaarden moeten worden overschreven voor specifieke doeleinden. In Drupal 7 bestond de globale variabele $conf, die meestal in settings.php werd gevuld met voorwaardelijke overschrijvingswaarden voor configuratie. Een groot nadeel van dit systeem was dat de overschrijvingen in de daadwerkelijke configuratie terechtkwamen. Wanneer een configuratieformulier met overschreven waarden werd opgeslagen, werden die voorwaardelijke overschrijvingen onderdeel van de configuratieopslag.

Drupal 8 introduceert een configuratie-override systeem dat:

• Deze overschrijvingen ondersteunt als tijdelijke lagen bovenop de standaardconfiguratiewaarden
• Geen overschreven waarden gebruikt in configuratieformulieren
• Overschrijvingen kan opslaan samen met andere configuratiebestanden voor ondersteuning van staging en versiebeheer (bijv. in het geval van taaloverschrijvingen; zie hieronder).

De globale variabele $conf in Drupal 7 is hernoemd naar $config in Drupal 8 en wordt standaard in het configuratiesysteem ingeschakeld.

Globale overschrijvingen

Drupal 8 behoudt de mogelijkheid om global $config te gebruiken. Het configuratiesysteem voegt deze overschrijvingswaarden samen via de implementatie van Drupal\Core\Config\ConfigFactory::get(). Wanneer u een waarde uit de configuratie opvraagt, krijgt de globale variabele $config de kans om de geretourneerde waarde te wijzigen:

// Haal de systeemonderhoudsboodschap op. Deze waarde kan standaard worden
// overschreven via global $config (evenals vertalingen, zie hieronder).
$message = \Drupal::config('system.maintenance')->get('message');

Om configuratiewaarden in global $config te overschrijven, bijvoorbeeld in settings.php, verwijst u naar hun configuratiesleutels:

$config['system.maintenance']['message'] = 'Sorry, onze site is tijdelijk offline.';

Voor geneste waarden gebruikt u geneste array-sleutels:

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

Wanneer u $config buiten settings.php gebruikt, gebruikt u de globale $config zoals eerder;

Het kan nuttig zijn om beschikbare configuratievariabelen op een van de volgende manieren te ontdekken:

• ze te bekijken via de module “Configuration Manager” in de UI op /admin/config/development/configuration/single/export
• uw siteconfiguratie YML-bestanden rechtstreeks te controleren,
• of ze op te vragen via drush.

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

Let op: waarden die via $config in settings.php zijn overschreven, zijn niet zichtbaar in de Drupal admin UI (totdat #2408549: configuratieformulieren markeren niet welke waarden overschreven zijn opgelost is, kunt u modules gebruiken zoals Configuration Override Warn of Config Override Inspector) of via drush-checks (tenzij u de vlag --include-overridden toevoegt). De admin-UI toont waarden die in de configuratie zijn opgeslagen, zodat u wijzigingen kunt doorvoeren in andere omgevingen die geen overschrijvingen hebben.

Voorbeeld van het overschrijven van API-sleutels om veiligheidsredenen: Overschrijven van Commerce Gateway API-sleutels

Overschrijvingen vermijden

U kunt configuratie ophalen zonder overschrijvingen om toegang te krijgen tot de originele configuratiewaarde (bijv. om zelfs globale overschrijvingen uit te schakelen). Dit is nuttig wanneer u een configuratieformulier schrijft. Het is belangrijk om voor formulieren onbewerkte waarden te gebruiken, zodat overschreven waarden niet per ongeluk in de opgeslagen configuratie terechtkomen. Dit is nog nuttiger in meertalige omgevingen, waar configuratiewaarden vaak worden overschreven door vertalingen.

Voorbeelden van configuratie ophalen met en zonder overschrijvingen:

// Haal de sitenaam op, met overschrijvingen.
$site_name = \Drupal::config('system.site')->get('name');

// Haal de sitenaam op, zonder overschrijvingen.
$site_name = \Drupal::config('system.site')->getOriginal('name', FALSE);
// Bewerkbare configuratie is altijd zonder overschrijvingen.
$site_name = \Drupal::configFactory()->getEditable('system.site')->get('name');

U kunt ook direct toegang krijgen tot de configuratieopslag via de service config.storage, die StorageInterface::read() implementeert. Dit is echter zelden de juiste manier om configuratie te benaderen.

Taaloverschrijvingen

Bijvoorbeeld: om een e-mail naar een gebruiker te sturen, moet de configuratie in de taal van de gebruiker zijn, niet in de taal van de pagina. Onthoud de eerder ingestelde taal, stel de juiste taal in op basis van de gebruiker, voer de bewerking uit en zet de taal weer terug:

// Laad de language_manager service.
$language_manager = \Drupal::service('language_manager');

// Haal de gewenste taal van de gebruiker op.
$langcode = $account->getPreferredLangcode();
$language = $language_manager->getLanguage($langcode);

// Onthoud de originele taal.
$original_language = $language_manager->getConfigOverrideLanguage();
// Stel de configuratie-overschrijvings-taal in.
$language_manager->setConfigOverrideLanguage($language);

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

// Stuur nu de e-mail op basis van $mail_config in de juiste taal.

// Zet de configuratietaal terug.
$language_manager->setConfigOverrideLanguage($original_language);

Het systeem van taaloverschrijvingen gebruikt ook configuratieopslag om overschrijvingen te bewaren (in tegenstelling tot de globale $config overschrijvingen). Taaloverschrijvingen worden opgeslagen in bestanden die zijn vernoemd naar hun originele configuratiebestand. Bijvoorbeeld: voor user.mail zal een taaloverschrijving heten: language.config.$langcode.user.mail. Bestanden beginnen met de prefix language.config., daarna de taalcodes, en vervolgens de originele configuratiesleutel. Het opslaan samen met de normale configuratie ondersteunt gefaseerde vertaling en kan worden gewijzigd zoals de basisconfiguratie.

Hoe worden deze taaloverschrijvingsbestanden gemaakt? De locale-module integreert met systeemgebeurtenissen om vertaalbestanden te maken voor meegeleverde configuratie op basis van configuratieschema-informatie. Er is ook de config translation core-module die een UI biedt om configuratie te vertalen op basis van schema. Deze werkt zowel met meegeleverde als met custom configuratie en gebruikt dezelfde taaloverschrijvingsbestanden.

Overschrijvingen aanbieden vanuit modules

Het is ook mogelijk om overschrijvingen op module-niveau te voorzien. Terwijl Drupal-core globale overschrijvingen en taaloverschrijvingen ondersteunt, zijn er veel andere use cases: op basis van gebruikersrollen, context, domeinen, groepen enz. Modules kunnen hun eigen criteria definiëren.

Wanneer ConfigFactory module-overschrijvingen verzamelt, roept het alle services aan die getagd zijn als config.factory.override:

config_example.services.yml

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

Stel de prioriteit van de subscriber in om te bepalen welke overschrijvingen voorrang krijgen. Hogere prioriteiten hebben voorrang op lagere bij dezelfde configuratienaam.

src/Config/ConfigExampleOverrides.php

namespace Drupal\config_example\Config;

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

/**
 * Voorbeeld van een configuratie-override.
 */
class ConfigExampleOverrides implements ConfigFactoryOverrideInterface {

  /**
   * {@inheritdoc}
   */
  public function loadOverrides($names) {
    $overrides = array();
    if (in_array('system.site', $names)) {
      $overrides['system.site'] = ['name' => 'Overridden site name!'];
    }
    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;
  }

}

Configuratie-overschrijvingen werken op drie niveaus: language, modules en settings.php, waarbij de laatste de hoogste prioriteit heeft. Overschrijvingen in settings.php hebben voorrang op die van modules. Module-overschrijvingen hebben voorrang op taaloverschrijvingen. De prioriteit van de event subscriber voor module-overschrijvingen bepaalt enkel de volgorde tussen verschillende modules, niet ten opzichte van taal of settings.php.

Houd er rekening mee dat configuratieformulieren in Drupal Core geen overschreven waarden gebruiken. In het bovenstaande module-voorbeeld ziet u dus niet “Overridden site name!” in /admin/config/system/site-information.

Belangrijk: als u de originele configuratiewaarden in uw override moet lezen (bijv. om te vergelijken of samen te voegen), gebruik dan \Drupal::configFactory in plaats van \Drupal::config, om recursieve loops te vermijden:

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

Meer achtergrondinformatie

Het override-systeem in zijn huidige vorm werd toegevoegd in #2098119: Vervang het config context systeem door ingebouwde locale- en event-based overschrijvingen

Zie voor historische / verouderde info: #1646580: Implementatie van configuratie-events en luisteraars en storage scopes voor gelokaliseerde configuratie, waar het override-systeem oorspronkelijk werd voorgesteld, evenals #1763640: Introduceer config context om originele configuratie en overschrijvingen toegankelijk te maken. Taal-specifieke overschrijvingen werden later toegevoegd in #2020361: Maak LanguageConfigContext om taalgebaseerde configuratie-overschrijvingen te activeren.