Sistema di sovrascrittura della configurazione

03/10/2025, by Ivan

Il sistema di configurazione di Drupal 8 gestisce la configurazione in modo unificato. Per impostazione predefinita Drupal salva i dati di configurazione nel database, ma è possibile esportarli in file YAML, il che consente di gestire la configurazione tramite il controllo di versione. Tuttavia, esistono casi in cui è necessario sovrascrivere i valori di configurazione per scopi specifici. In Drupal 7 esisteva la variabile globale $conf, che di solito veniva popolata in settings.php con valori di sovrascrittura condizionali per la configurazione. Un grande svantaggio di quel sistema era che le sovrascritture finivano nella configurazione effettiva. Quando un form di configurazione che conteneva valori sovrascritti veniva salvato, la sovrascrittura condizionale veniva scritta nello storage della configurazione reale.

Drupal 8 introduce un sistema di sovrascrittura della configurazione che:

Gestisce queste sovrascritture come strati temporanei sopra i valori standard di configurazione
Non utilizza i valori sovrascritti nei form di configurazione
Può salvare le sovrascritture insieme ad altri file di configurazione per supportare staging e controllo di versione (ad esempio nel caso di sovrascritture linguistiche; vedi sotto).

La variabile globale $conf di Drupal 7 è stata rinominata in $config in Drupal 8 ed è attiva nel sistema di configurazione per impostazione predefinita.

Sovrascritture globali

Drupal 8 mantiene la possibilità di usare la variabile globale $config. Il sistema di configurazione fonde questi valori di sovrascrittura tramite l’implementazione di Drupal\Core\Config\ConfigFactory::get(). Quando recuperi un valore dalla configurazione, la variabile globale $config può modificarne il valore restituito:

// Ottieni il messaggio di manutenzione del sito. Questo valore può essere
// sovrascritto da global $config (così come dalle traduzioni, vedi sotto).
$message = \Drupal::config('system.maintenance')->get('message');

Per sovrascrivere valori di configurazione in $config globale, ad esempio in settings.php, fai riferimento alle loro chiavi di configurazione:

$config['system.maintenance']['message'] = 'Sorry, our site is down now.';

Per valori annidati, usa le chiavi degli array annidati:

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

Quando usi $config al di fuori di settings.php, ricorda che si riferisce sempre alla variabile globale.

Può essere utile determinare le variabili di configurazione disponibili in uno dei seguenti modi:

visualizzandole con il modulo «Configuration Manager» tramite l’interfaccia in /admin/config/development/configuration/single/export
controllando direttamente i tuoi file YAML di configurazione del sito,
oppure richiedendole con drush.

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

Nota che i valori sovrascritti con $config in settings.php non saranno visibili nell’interfaccia di amministrazione di Drupal (fino a #2408549, quando sarà possibile usare moduli come Configuration Override Warn o Config Override Inspector) né nelle verifiche via drush (a meno che non aggiungi il flag --include-overridden). L’interfaccia mostra solo i valori salvati in configurazione, così puoi applicare modifiche in ambienti che non hanno le stesse sovrascritture.

Un esempio di sovrascrittura delle chiavi API per motivi di sicurezza è disponibile qui: Sovrascrivere le chiavi API del Commerce Gateway

Evitare le sovrascritture

Puoi ottenere la configurazione senza sovrascritture per accedere al valore originale (utile, ad esempio, nei form di configurazione). È importante usare valori non sovrascritti nei form, così non finiranno nella configurazione salvata. È ancora più utile in ambienti multilingua, dove i valori possono essere sovrascritti dalle traduzioni.

// Ottieni il nome del sito con le sovrascritture.
$site_name = \Drupal::config('system.site')->get('name');

// Ottieni il nome del sito senza sovrascritture.
$site_name = \Drupal::config('system.site')->getOriginal('name', FALSE);
// Nota: la config mutabile è sempre senza sovrascritture.
$site_name = \Drupal::configFactory()->getEditable('system.site')->get('name');

Puoi anche accedere direttamente allo storage tramite il servizio config.storage, che implementa StorageInterface::read(), ma questo raramente è il modo corretto di accedere alla configurazione.

Sovrascritture linguistiche

Ad esempio, per inviare un’email a un utente, la configurazione dovrebbe essere nella lingua dell’utente e non della pagina. Occorre ricordare la lingua originale, impostare quella dell’utente, eseguire le operazioni e poi ripristinarla:

$language_manager = \Drupal::service('language_manager');
$langcode = $account->getPreferredLangcode();
$language = $language_manager->getLanguage($langcode);

$original_language = $language_manager->getConfigOverrideLanguage();
$language_manager->setConfigOverrideLanguage($language);

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

// Invia email con $mail_config nella lingua corretta.

$language_manager->setConfigOverrideLanguage($original_language);

Le sovrascritture linguistiche usano anch’esse lo storage di configurazione. Vengono salvate in file chiamati con il nome base del file sorgente, ad esempio: language.config.$langcode.user.mail. I file di sovrascrittura linguistica seguono il prefisso language.config., poi il codice della lingua, e poi la chiave della configurazione originale. Questo sistema consente traduzioni incrementali della configurazione e modifiche come se fossero configurazioni normali.

Questi file vengono creati dal modulo Locale, che si integra con gli eventi di sistema per generare file di traduzione basati sulle informazioni di schema della configurazione. Esiste anche il modulo core di traduzione configurazione, che fornisce un’interfaccia per tradurre configurazioni basate sugli schemi, sia fornite che personalizzate.

Fornire sovrascritture dai moduli

È anche possibile fornire sovrascritture a livello di modulo. Oltre alle sovrascritture globali e linguistiche, esistono casi d’uso per sovrascritture basate su ruoli utente, contesto, dominio, gruppi e così via. I moduli possono definire i propri criteri.

Quando ConfigFactory raccoglie le sovrascritture, chiama i servizi taggati con config.factory.override:

config_example.services.yml

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

Il parametro priority definisce la precedenza: le sovrascritture con priorità più alta prevalgono su quelle con priorità più bassa (a parità di nome di configurazione).

src/Config/ConfigExampleOverrides.php

namespace Drupal\config_example\Config;

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

/**
 * Example configuration override.
 */
class ConfigExampleOverrides implements ConfigFactoryOverrideInterface {

  public function loadOverrides($names) {
    $overrides = [];
    if (in_array('system.site', $names)) {
      $overrides['system.site'] = ['name' => 'Overridden site name!'];
    }
    return $overrides;
  }

  public function getCacheSuffix() {
    return 'ConfigExampleOverrider';
  }

  public function getCacheableMetadata($name) {
    return new CacheableMetadata();
  }

  public function createConfigObject($name, $collection = StorageInterface::DEFAULT_COLLECTION) {
    return NULL;
  }
}

Le sovrascritture operano a tre livelli: lingua, moduli e settings.php, con quest’ultimo che ha la priorità più alta. Le sovrascritture in settings.php hanno precedenza su quelle fornite dai moduli, e quelle fornite dai moduli hanno precedenza su quelle linguistiche. La priorità impostata nei moduli serve solo a regolare la precedenza tra moduli, non rispetto a lingue o settings.php.

Ricorda che i form di configurazione nel core di Drupal non mostrano i valori sovrascritti. Nell’esempio sopra, non vedrai «Overridden site name!» in /admin/config/system/site-information.

Se devi leggere i valori originali nella tua logica di override (ad esempio per confronti), caricali da \Drupal::configFactory invece di \Drupal::config per evitare loop ricorsivi:

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

Ulteriori informazioni

Il sistema di sovrascritture nella sua forma attuale è stato introdotto in ~~#2098119: Replace the config context system with built-in locale support and single event based overrides~~.

Per informazioni storiche/obsolete vedi ~~#1646580: Implement config events and listeners and storage scopes for localized config~~ e ~~#1763640: Introduce config context to make original config and overrides available~~. Le sovrascritture specifiche per lingua sono state aggiunte in ~~#2020361: Create LanguageConfigContext to enable language-based config overrides~~.

Extra Block Types (EBT) - Nuova esperienza con Layout Builder❗

❗Extra Paragraph Types (EPT) - Nuova esperienza con Paragraphs