Schema di configurazione / metadati

Drupal 8 include il supporto per un linguaggio di schema/metadati creato con Kwalify (http://www.kuwata-lab.com/kwalify/) per i file di configurazione YAML. Kwalify stesso è scritto in Ruby, e sono state necessarie alcune piccole modifiche al formato, quindi non tutti i dettagli di Kwalify si applicano direttamente, ma è comunque molto simile.

Cheatsheet

Per una comprensione rapida e alcuni esempi pratici, guarda questa cheatsheet e poi continua a leggere se hai ancora domande:

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

Esempio introduttivo

Il modulo System ha due impostazioni di configurazione relative alla modalità di manutenzione (se il sito è messo offline per i visitatori normali):

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

(Il fatto che la manutenzione sia attiva è memorizzato nel sistema state, non nella configurazione.)

I valori predefiniti per questo oggetto di configurazione si trovano in core/modules/system/config/install/system.maintenance.yml come:

message: '@site è attualmente in manutenzione. Torneremo presto. Grazie per la pazienza.'
langcode: en

Ogni modulo può avere tanti oggetti di configurazione quanti ne servono. Tutto ciò è descritto in uno o più file di schema che vengono distribuiti insieme al modulo. Nel caso del modulo System, i file si trovano in core/modules/system/config/schema. La sezione rilevante dello schema dal file system.schema.yml appare così:

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

La chiave di livello superiore ("system.maintenance") nel file si riferisce al nome base del file .yml ("system.maintenance.yml") e al nome dell’oggetto di configurazione (config('system.maintenance')). I livelli annidati descrivono cosa c’è nel file. Lo schema di configurazione predefinisce due tipi di file di configurazione: config_object per i file di configurazione globali e config_entity per le entità. Il tipo config_object è definito in core.data_types.schema.yml come segue:

# 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

Il mapping è il tipo base per coppie chiave-valore. Usando il tipo config_object, la definizione della modalità di manutenzione riutilizza le chiavi langcode e _core e aggiunge un’altra chiave per il messaggio. Tornando alla definizione di system.maintenance, l’etichetta della schema label:'Maintenance mode' descrive il contenuto dello schema. Poi gli elementi effettivi sono elencati sotto la chiave mapping, dove è definita la chiave message, ereditando langcode e _core dal tipo base. Ogni elemento ha un tipo e una chiave label, che descrivono il tipo di dato e forniscono una descrizione. L’etichetta di solito coincide o è simile a quella del modulo di configurazione dove il valore può essere modificato dall’amministratore di sistema.

In tutti i casi supportati dal core, l’elemento di livello superiore nel file .yml sarà un mapping con elementi descritti in fondo alla lista di mapping. Bisogna usare uno dei due sottotipi definiti di mapping: config_object o config_entity. I singoli elementi del mapping possono essere di qualsiasi tipo a seconda di come sono definiti i dati. La chiave _core e tutte le chiavi in _core sono riservate al core di Drupal.

A cosa servono i file di schema?

1. Lo scopo principale iniziale era il supporto multilingua. Serve uno strumento per identificare tutte le stringhe traducibili nella configurazione fornita, così quando distribuisci le tue impostazioni, viste predefinite, ruoli utente aggiuntivi, voci di menu ecc., possiamo offrirle alla traduzione come parte del tuo modulo/tema su https://localize.drupal.org. Per questo scopo bastano i livelli e i tipi di annidamento.

2. Usiamo gli schemi anche per fornire moduli reali di traduzione basati sui tuoi dati. In questo caso i tipi assumono più importanza e le etichette diventano fondamentali. Il modulo di traduzione della configurazione core usa gli schemi per costruire i form di traduzione e salvare le traduzioni. I due tipi traducibili più importanti sono label (per input testuali a riga singola) e text (per input testuali multi-riga).

3. Grazie alla conoscenza incorporata negli schemi di configurazione su cosa è memorizzato nell’oggetto di configurazione, la persistenza predefinita delle entità di configurazione richiede uno schema per poter esportare le proprietà corrette con i tipi definiti. Anche se è meglio fornire sempre schemi, se davvero non vuoi farlo, puoi implementare il metodo toArray() nella tua entità di configurazione per evitare di richiedere uno schema.

4. Lo schema di configurazione viene anche usato per legare automaticamente i valori ai tipi attesi. Questo assicura che, anche se PHP e le web form in generale preferiscono stringhe, la configurazione venga salvata con i tipi corretti. Questo è importante affinché nelle differenze (diff) di configurazione vengano mostrati solo cambiamenti reali e non cambiamenti di tipo accidentali.

5. In PHPUnit tutti i test derivati da TestBase applicano per default uno schema rigoroso. Questo genera errori se lo schema manca o non è valido. Anche se non è raccomandato, è possibile disattivarlo nei test impostando:

protected $strictConfigSchema = FALSE;

Vedi https://drupal.org/project/config_inspector per un modulo che aiuta a fare debug degli schemi. Questo modulo aiuta a trovare schemi mancanti e differenze con varie viste dei dati e dello schema.

Ci sono altre idee di utilizzo per gli schemi che possono essere implementate nei moduli, ad esempio per la creazione di interfacce web service. Probabilmente emergeranno altri casi d’uso non ancora previsti.