API di configurazione semplice

In questa pagina viene descritto l’API per ottenere e impostare i dati di configurazione per la configurazione semplice. (Non si applica alle informazioni memorizzate negli oggetti di configurazione.)

Dati di configurazione

Ogni modulo può fornire una configurazione predefinita. Ad esempio, le impostazioni della modalità di manutenzione sono definite in core/modules/system/config/install/system.maintenance.yml. In questo file la prima parte rappresenta lo spazio dei nomi, che indica quale modulo ha fornito questa configurazione (il modulo system in questo esempio), seguito dalla sottosistema (maintenance in questo esempio). Il file deve trovarsi nella cartella config/install. Deve inoltre contenere il carattere «.» nel nome del file per la validazione in ConfigBase->validateName($name). Questo file contiene il seguente YAML:

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

La configurazione può anche essere annidata, come nelle impostazioni delle prestazioni (system.performance.yml):

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

IMPORTANTE: le chiavi radice devono essere una mappa

I dati alla radice della configurazione devono essere rappresentati come una mappa, non come una sequenza imprevedibile. Ad esempio, se memorizzi dati per ciascun tipo di entità disponibile, rendi la chiave padre il tipo di entità e aggiungi la chiave radice entity_type. Vedi l’esempio di struttura qui sotto:

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

Se i tipi di entità sono la chiave radice, non è possibile rappresentare la configurazione con uno schema. Inoltre, il core di Drupal non sarà in grado di aggiungere informazioni supplementari quando la configurazione viene installata come parte dell’installazione di un modulo (o di un tema).

Interazione con la configurazione

Interagisci con questi file tramite l’oggetto Config e crei un’istanza di questo oggetto chiamando la funzione config() con il nome del file senza l’estensione. La chiamata alla funzione config restituirà un’istanza di \Drupal\Core\Config\ImmutableConfig.

// Config immutabile (Sola Lettura).
$config = \Drupal::config('system.performance');

// Config mutabile (Lettura / Scrittura).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Una volta ottenuto l’oggetto Config, puoi interagirci in diversi modi.

Lettura della configurazione

La configurazione viene letta utilizzando il metodo get(). Questo può essere usato in diversi modi. Per leggere un frammento di configurazione, basta specificare la sua chiave.

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

Le chiamate a \Drupal::config() possono anche essere concatenate.

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

Per leggere la configurazione annidata, separa le chiavi con il carattere «.».

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

Puoi leggere la configurazione a qualsiasi livello se sotto il livello scelto ci sono configurazioni annidate in un array.

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

Questo restituirà un array con due chiavi - «enabled» e «max_age».

Per restituire tutti i dati in un oggetto di configurazione, basta chiamare get() senza argomenti.

Puoi anche restituire tutte le chiavi di configurazione disponibili nel sistema, o solo quelle che iniziano con una determinata sottostringa (prefisso $).

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

Scrittura della configurazione

Per modificare la configurazione, è necessario ottenere un’istanza di \Drupal\Core\Config\Config (oggetto di configurazione modificabile), chiamando getEditable() sulla fabbrica di configurazioni. Tentare di modificare o chiamare delete() / save() su un’istanza di \Drupal\Core\Config\ImmutableConfig genererà un’eccezione ImmutableConfigException.

Questo si fa in questo modo:

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

La configurazione viene modificata o aggiunta con il metodo set() e salvata con il metodo save(). Nota che la configurazione deve essere esplicitamente salvata; impostare semplicemente i dati nella configurazione non li salva.

Salvi i dati in un oggetto di configurazione nello stesso modo in cui li leggi, facendo riferimento alle chiavi e salvando i dati corrispondenti. La sintassi è la stessa di variable_set(), che era presente nelle versioni precedenti di Drupal.

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

// Imposta un valore scalare.
$config->set('cache.page.enabled', 1);

// Imposta un array di valori.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Salva i dati nel database.
$config->save();

La funzione set() è anche concatenabile, quindi, se devi modificare solo un valore, puoi farlo in una sola riga di codice.

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

Se vuoi sostituire tutti i dati in un oggetto di configurazione, usa la funzione setData(). Non puoi usare setData() per sostituire solo un sottoinsieme di dati – se vuoi sostituire meno dell’intero oggetto, devi usare una o più chiamate a set(). Quando usi setData() devi specificare ogni chiave e valore nello stesso formato di array associativo che viene restituito da get() senza argomenti. Per i parametri di prestazioni del sistema in system.performance.yml, sarà così:

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

Eliminazione della configurazione

Singoli valori di configurazione possono essere azzerati con la funzione clear(), che è anch’essa concatenabile.

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

In questo esempio $page_cache_data restituirà un array con una sola chiave – «enabled» – perché «max_age» è stato rimosso.

Tutti i set di configurazione possono essere eliminati con la funzione delete().

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

Nota che dopo questo non devi chiamare la funzione save(), poiché ciò creerebbe una versione vuota del set di configurazione.

Best practice

Evita di creare più volte istanze dello stesso oggetto di configurazione all’interno della stessa funzione, poiché ciò riduce le prestazioni. Il seguente codice crea inutilmente due volte un’istanza dell’oggetto di configurazione «foo.bar».

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

La soluzione migliore è creare l’istanza dell’oggetto di configurazione una sola volta, salvarla in una variabile e lavorare con quella variabile per il resto del codice.

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

Iniezione di valori di configurazione nei servizi

I valori di configurazione possono essere iniettati nel tuo servizio personalizzato usando una factory del servizio.

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

L’esempio è stato adattato da Come iniettare valori di configurazione nei servizi?