Definitie en gebruik van je eigen configuratie in Drupal 8
Hoofdonderwerp: het definiëren van je eigen configuratie
Je kunt standaardconfiguratie opnemen in je module, gebaseerd op de functionaliteit van andere modules (contenttypes, views, velden, tekstformaten, enz.).
Bijvoorbeeld: de node-module levert configuratie voor een contenttype, dus in je eigen module kun je een standaard contenttype configureren dat samen met je module geleverd kan worden.
Misschien wil je configuratie definiëren voor je eigen plugins, entiteiten en instellingen, die op hun beurt door andere modules gebruikt kunnen worden, net zoals jij de configuratie van een node-contenttype kunt gebruiken. Drupal 8 maakt het eenvoudig om je eigen configuratie te definiëren.
Configuratiebestand
Configuratiebestanden voor je module staan in de submap config/install van je module. Dus: /modules/example/config/install/example.settings.yml, als je module in /modules/example staat. Je kunt hier configuratiebestanden plaatsen in YAML-formaat.
Hoewel het niet verplicht is, wordt sterk aangeraden de configuratiebestanden van je module te benoemen met de prefix van de modulenaam: bijvoorbeeld example.settings.yml voor configuratie-instellingen. Noem het bestand niet settings.yml of system.settings.yml, omdat dit kan conflicteren met andere bestanden. Als je deze conventie niet volgt, kunnen Drush-commando’s zoals drush config:import in de war raken.
Op dezelfde manier kun je configuratie leveren voor andere componenten, bijvoorbeeld een voorbeeld van een contenttype, door standaardconfiguratie op te nemen in je module, waarbij het bestand node.type.example_mytype.yml de configuratie identificeert die door de node-module wordt verwerkt als een contenttype.
De bestandsnaam van de configuratie (zonder de extensie .yml) is ook de configuratienaam in het systeem, en dit is hoe je vanuit de PHP API toegang krijgt tot je configuratie.
Structuur van een configuratiebestand
Een configuratiebestand moet YAML gebruiken. Je kunt de structuur volledig zelf bepalen, zolang het YAML-formaat correct is. Bijvoorbeeld: als je een parameter wilt die iets specifieks weergeeft vanuit je page controller, kan het bestand een sleutel message bevatten met een stringwaarde:
message: 'Hello' langcode: 'en'
Het wordt aangeraden de taalcode van het bestand op te nemen onder de sleutel langcode. Dit wordt door het taalsysteem gebruikt om vertaalbare tekst aan te bieden. De sleutel langcode is hiervoor gereserveerd en mag op het hoogste niveau niet voor iets anders gebruikt worden.
Voor vertaling van configuratie moet de config translation module geïnstalleerd zijn.
Om configuratie vertaalbaar te maken, moet je nog twee bestanden toevoegen:
- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml
Het eerste bestand definieert het schema van je configuratie. We definiëren example.settings als een config_object met meerdere velden. Elk veld heeft een type: het basistype bepaalt of het veld vertaalbaar is of niet (zie core.data_types.schema.yml). Bijvoorbeeld: een path met een interne Drupal-pad is niet vertaalbaar, maar een text-veld wel.
# /modules/example/config/schema/example.schema.yml
example.settings:
type: config_object
label: 'Example config'
mapping:
message:
type: text
label: 'Message'
Het tweede bestand voegt een koppeling toe naar /admin/config/regional/config-translation in het vertaalformulier:
# /modules/example/example.config_translation.yml
example.admin.config:
title: 'Example module'
base_route_name: example.admin.config
names:
- example.settings
Volgens conventie komt de sleutel overeen met de basisroute: example.admin.config is de route naar het configuratieformulier van je module. names somt alle configuratiesleutels op die in het formulier bewerkt worden – in dit geval de configuratie die hierboven in het schema gedefinieerd is.
Het bestand kan ook complexere lijsten en key/value-paren in boomstructuren bevatten. Zie bijvoorbeeld het bestand views.view.content.yml voor een meer uitgebreid configuratievoorbeeld.
Config translation voegt automatisch een tabblad “Translate” toe in het configuratieformulier van de module, maar dit verschijnt niet als het het enige tabblad is. Om een standaard-tabblad toe te voegen aan het configuratieformulier, moeten we nog een bestand example.links.task.yml toevoegen. (Zie Module-gedefinieerde lokale taken.)
// example.links.task.yml example.admin.config: route_name: example.admin.config title: Settings base_route: example.admin.config
Gebruik van configuratie
Drupal 8 bevat een PHP API om configuratie te lezen en te schrijven. De eenvoudigste manier is de statische methode Drupal::config():
$config = \Drupal::config('example.settings');
// Print 'Hello'.
print $config->get('message');
// Print 'en'.
print $config->get('langcode');
Als je configuratie wilt bewerken en opslaan met een nieuwe waarde, gebruik je \Drupal::service('config.factory')->getEditable():
$config = \Drupal::service('config.factory')->getEditable('example.settings');
// Stel nieuwe message-waarde in en sla op.
$config->set('message', 'Hi')->save();
// Print nu 'Hi'.
print $config->get('message');