Configuratieschema/metadata

Drupal 8 bevat ondersteuning voor een schema-/metadata-taal, gemaakt met Kwalify (http://www.kuwata-lab.com/kwalify/) voor YAML-configuratiebestanden. Kwalify zelf is geschreven in Ruby, en er waren enkele kleine aanpassingen nodig aan het formaat, waardoor niet alle details van Kwalify direct toepasbaar zijn, maar het komt er vrij dicht bij in de buurt.

Cheatsheet

Voor een snel overzicht en enkele handige voorbeelden, bekijk deze cheatsheet en lees verder als u nog vragen hebt:

/sites/default/files/config-schema-cheat-sheet1.5.pdf

Inleidend voorbeeld

De system-module heeft twee configuratieparameters die verband houden met onderhoudsmodus (of de site offline is voor gewone bezoekers):

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

(Of onderhoud is ingeschakeld, wordt opgeslagen in het state system, en niet in de configuratie.)

Standaardwaarden voor dit configuratieobject worden opgeslagen in core/modules/system/config/install/system.maintenance.yml als:

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

Elke module kan zoveel configuratieobjecten hebben als nodig. Dit alles wordt uitgelegd in een of meer schema-bestanden die met de module worden meegeleverd. In het geval van de system-module bevinden de bestanden zich in core/modules/system/config/schema. Het relevante gedeelte van het schema uit system.schema.yml ziet er als volgt uit:

system.maintenance:
  type: config_object
  label: 'Maintenance mode'
  mapping:
    message:
      type: text
      label: 'Message to display when in maintenance mode'

De toplevel key ("system.maintenance") in het bestand verwijst naar de basisbestandsnaam van het .yml-bestand ("system.maintenance.yml") en naar de naam van het configuratieobject (config('system.maintenance')). Geneste niveaus beschrijven wat er in het bestand staat. Het configuratieschema definieert twee vooraf bepaalde typen configuratiebestanden: config_object voor globale configuratiebestanden en config_entity voor entiteiten. Het type config_object is gedefinieerd in core.data_types.schema.yml als volgt:

# Root of a configuration object.

_core_config_info:
  type: mapping
  mapping:
    default_config_hash:
      type: string
      label: 'Default configuration hash'

config_object:
  type: mapping
  mapping:
    langcode:
      type: string
      label: 'Language code'
    _core:
      type: _core_config_info

Mapping is het basistype voor key-value paren. Door het type config_object te gebruiken, hergebruikt de definitie van onderhoudsmodus de sleutels langcode en _core en voegt er een sleutel aan toe voor het eigenlijke bericht. In de definitie system.maintenance beschrijft het schema-label label:'Maintenance mode' de inhoud van het schema. De feitelijke elementen worden vervolgens opgesomd onder de mapping key, waar de sleutel message is gedefinieerd, terwijl langcode en _core worden geërfd van het basistype. Elk element heeft een type en een label, dat respectievelijk het datatype en de beschrijving van de gegevens geeft. Het label is doorgaans hetzelfde of vergelijkbaar met het label van het configuratieformulier waar de waarde door een beheerder kan worden bewerkt.

In alle door de core ondersteunde gevallen zal het toplevel-element in het .yml-bestand een mapping zijn met de elementen die worden beschreven in de mappinglijst eronder. U moet een van de twee gedefinieerde subtypes mapping gebruiken: config_object of config_entity. De afzonderlijke elementen in de mapping kunnen van elk type zijn, afhankelijk van hoe u de gegevens hebt gedefinieerd. De sleutel _core en alle sleutels in _core zijn gereserveerd voor de Drupal-core.

Waarvoor worden schema-bestanden gebruikt?

1. De belangrijkste use case voor schema’s was meertalige ondersteuning. We moeten een hulpmiddel hebben om alle vertaalbare strings in de geleverde configuratie te identificeren, zodat wanneer u uw eigen instellingen, standaardviews, extra gebruikersrollen, menu-items, enz. levert, we deze kunnen aanbieden voor vertaling als onderdeel van uw module-/themarelease op https://localize.drupal.org. Voor dit gebruik zijn de niveaus en typen van nesting voldoende.

2. We gebruiken schema’s ook om echte vertaalformulieren te bieden voor configuratie op basis van uw gegevens. In dit geval zijn types belangrijker, en labels essentieel. De module config translation gebruikt schema’s om vertaalformulieren te genereren en vertalingen op te slaan. De twee belangrijkste ingebouwde vertaalbare types zijn “label” voor enkelregelige invoer en “text” voor meerregelige invoer.

3. Dankzij de kennis die in configuratieschema’s is ingebouwd over wat er in een configuratieobject wordt opgeslagen, vereist de standaard persistentie-implementatie van configuratieobjecten een configuratieschema voor het object, zodat de juiste eigenschappen met de juiste types worden geëxporteerd. Hoewel het beter is schema’s te voorzien, kunt u, als u dit niet wilt, de methode toArray() implementeren in uw configuratie-entiteit om te voorkomen dat een schema nodig is.

4. Het configuratieschema wordt ook gebruikt voor automatische typecasting van waarden. Dit garandeert dat, hoewel PHP en webformulieren meestal strings gebruiken, de juiste types worden gebruikt bij het opslaan van configuratie. Dit is belangrijk om ervoor te zorgen dat bij configuratiedeployments alleen echte wijzigingen worden weergegeven, niet willekeurige typewijzigingen.

5. In PHPUnit handhaven alle afgeleide TestBase-tests strikt de configuratieschema’s standaard. Dit resulteert in schemafouten als een schemabestand ontbreekt of ongeldig is. Hoewel dit niet wordt aanbevolen, kan het worden overgeslagen door in uw test in te stellen:

protected $strictConfigSchema = FALSE;

Zie https://drupal.org/project/config_inspector voor een module die helpt bij het debuggen van schema’s. De module helpt bij het vinden van ontbrekende schema’s en schema-elementen met verschillende weergaven van uw gegevens en schema.

Er zijn andere ideeën voor schema’s die modules kunnen leveren, zoals het genereren van webservice-interfaces op basis daarvan. Waarschijnlijk zijn er nog andere toepassingen die mensen zullen ontdekken.