Sistema de anulación de configuración

El sistema de configuración de Drupal 8 maneja la configuración de forma unificada. Por defecto, Drupal almacena los datos de configuración en la base de datos, pero pueden exportarse a archivos YAML, lo que permite gestionar la configuración mediante control de versiones. Sin embargo, hay casos en los que es necesario anular valores de configuración para ciertos propósitos. En Drupal 7 existía la variable global $conf, que comúnmente se llenaba en settings.php con valores de anulación condicional para la configuración. Una gran desventaja de ese sistema era que las anulaciones pasaban a formar parte de la configuración real. Cuando se guardaba un formulario de configuración que contenía valores anulados, la anulación condicional se almacenaba en el repositorio de configuración real.

Drupal 8 presenta un sistema de anulación de configuración que:

• Soporta estas anulaciones como capas temporales sobre los valores estándar de configuración
• No utiliza los valores anulados para los formularios de configuración
• Puede almacenar las anulaciones con otros archivos de configuración para soportar staging y control de versiones (por ejemplo, en el caso de anulaciones de idiomas; ver más abajo).

La variable global $conf en Drupal 7 fue renombrada a $config en Drupal 8 y está activada en el sistema de configuración por defecto.

Anulaciones globales

Drupal 8 mantiene la posibilidad de usar la variable global $config. El sistema de configuración combina estos valores anulados a través de la implementación Drupal\Core\Config\ConfigFactory::get(). Cuando se extrae un valor de la configuración, la variable global $config tiene la oportunidad de modificar el valor retornado:

// Obtener el texto del mensaje de mantenimiento del sitio del sistema. Este valor puede ser anulado por
// defecto desde la variable global $config (así como por traducciones, ver más abajo).
$message = \Drupal::config('system.maintenance')->get('message');

Para anular valores de configuración en el $config global, por ejemplo en settings.php, diríjase a sus claves de configuración:

$config['system.maintenance']['message'] = 'Lo sentimos, nuestro sitio está temporalmente fuera de servicio.';

Para valores anidados, use claves de array anidado:

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

Cuando use $config fuera del archivo settings.php, use la variable global $config anterior;

Puede ser útil determinar las variables de configuración disponibles por uno de los siguientes medios:

• Verlas mediante el módulo "Configuration Manager" usando la interfaz en /admin/config/development/configuration/single/export
• Revisar directamente sus archivos YAML de configuración del sitio,
• O consultarlas usando drush.

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

Tenga en cuenta que los valores anulados mediante $config en settings.php no estarán disponibles para visualización desde la interfaz administrativa de Drupal (hasta #2408549: en formularios de configuración no se indica si los valores están anulados, a menos que use Configuration Override Warn o Config Override Inspector) o para revisión vía drush (a menos que agregue el flag --include-overridden). La interfaz administrativa muestra los valores almacenados en la configuración, para que pueda hacer cambios en otros entornos que no tienen anulaciones.

Un ejemplo de anulación de claves API por motivos de seguridad puede verse en: Anulación de claves API para pagos en Commerce Gateway

Evitar anulaciones

Puede obtener la configuración sin anulaciones para acceder al valor crudo de configuración (por ejemplo, para desactivar la aplicación incluso de las anulaciones globales). Esto es muy útil, por ejemplo, si está escribiendo un formulario de configuración. Es importante usar un entorno sin anulaciones para el formulario, para evitar que valores anulados se guarden en la configuración persistente. Esto es aún más útil si su código se usa en un entorno multilingüe, donde los valores de su configuración generalmente se anulan como traducciones.

Aquí algunos ejemplos para obtener configuración con y sin anulaciones.

// Obtener el nombre del sitio, con anulaciones.
$site_name = \Drupal::config('system.site')->get('name');

// Obtener el nombre del sitio sin anulaciones.
$site_name = \Drupal::config('system.site')->getOriginal('name', FALSE);
// Nota: la configuración mutable siempre está libre de anulaciones.
$site_name = \Drupal::configFactory()->getEditable('system.site')->get('name');

También puede acceder directamente al almacenamiento de configuración mediante el servicio config.storage, que implementa StorageInterface::read(). Sin embargo, raramente es la forma correcta de acceder a la configuración.

Anulaciones de idioma

Por ejemplo, para enviar un correo electrónico a un usuario, la configuración debe estar en el idioma del usuario, no en el del sitio. Recuerde el idioma usado anteriormente, establezca el idioma correcto basado en el usuario, realice operaciones basadas en la configuración y luego restablezca el idioma original:

// Cargar el servicio language_manager
$language_manager = \Drupal::service('language_manager');

// Obtener el objeto del idioma destino
$langcode = $account->getPreferredLangcode();
$language = $language_manager->getLanguage($langcode);

// Recordar el idioma original antes de esta operación.
$original_language = $language_manager->getConfigOverrideLanguage();
// Establecer el idioma objetivo de traducción en la fábrica de configuración.
$language_manager->setConfigOverrideLanguage($language);

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

// Ahora enviar el correo basado en $mail_config que está en el idioma correcto.

// Restaurar el idioma de configuración.
$language_manager->setConfigOverrideLanguage($original_language);

El sistema de anulaciones de idioma también utiliza el almacenamiento de configuración para guardar las anulaciones (a diferencia de las anulaciones globales basadas en $config). Las anulaciones de idioma se almacenan en archivos nombrados en función de su archivo base. Así, si existe una anulación para el idioma específico para el archivo de configuración user.mail mencionado arriba, se llamará language.config.$langcode.user.mail. Los archivos de anulación llevan el prefijo language.config., seguido del código de idioma y luego la clave de configuración original. Almacenar archivos con la configuración normal permite traducción gradual de la configuración y puede ser modificada al igual que la configuración base.

¿Cómo se crean originalmente estos archivos de anulación de idioma? El módulo local se integra con eventos del sistema para crear archivos de traducción para la configuración entregada basada en información del esquema de configuración. También existe un módulo principal de traducción de configuración que proporciona una interfaz común para traducir la configuración basada en esquemas. Funciona tanto con configuración entregada como con configuración personalizada y utiliza los mismos archivos de anulación de idioma.

Proporcionar anulaciones desde módulos

También es posible proporcionar una anulación a nivel de módulo desde cualquier módulo. Aunque Drupal Core soporta anulaciones globales y anulaciones basadas en idioma, existen casos de uso para muchos otros tipos de anulaciones, incluyendo basadas en roles de usuario, contexto, dominio, grupo, etc. Los módulos pueden definir sus propios criterios para realizar esas anulaciones.

Cuando ConfigFactory recopila las anulaciones proporcionadas por módulos, llama a cualquier servicio etiquetado como config.factory.override:

config_example.services.yml

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

Establezca la prioridad del suscriptor para indicar la prioridad de las anulaciones. Las anulaciones con mayor prioridad prevalecerán sobre las de menor prioridad (en caso de la misma configuración).

src/Config/ConfigExampleOverrides.php

namespace Drupal\config_example\Config;

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

/**
 * Ejemplo de anulación de configuración.
 */
class ConfigExampleOverrides implements ConfigFactoryOverrideInterface {

  /**
   * {@inheritdoc}
   */
  public function loadOverrides($names) {
    $overrides = array();
    if (in_array('system.site', $names)) {
      $overrides['system.site'] = ['name' => '¡Nombre de sitio anulado!'];
    }
    return $overrides;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheSuffix() {
    return 'ConfigExampleOverrider';
  }
  
  /**
   * {@inheritdoc}
   */
  public function getCacheableMetadata($name) {
    return new CacheableMetadata();
  }

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

}

Las anulaciones de configuración funcionan en tres niveles diferentes: idioma, módulos y settings.php, siendo este último el de mayor prioridad. Las anulaciones en settings.php tienen prioridad sobre los valores proporcionados por módulos. Las anulaciones proporcionadas por módulos tienen prioridad sobre el idioma. La prioridad del suscriptor de eventos para las anulaciones de módulos sólo establece prioridad en comparación con las anulaciones de otros módulos, no puede usarse para establecer una prioridad más alta respecto a anulaciones de idioma o settings.php.

Tenga en cuenta que los formularios de configuración en Drupal Core no usan valores anulados de configuración. En el ejemplo anterior de anulación de módulo, no verá "¡Nombre de sitio anulado!" en /admin/config/system/site-information.

Vale la pena reiterar que si necesita leer los valores originales de configuración en una anulación, por ejemplo para compararlos o fusionarlos, debe cargar desde \Drupal::configFactory, no desde \Drupal::config, para evitar ciclos anidados en su anulación: 

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

Más información de referencia

El sistema de anulaciones en su forma actual/final fue añadido en #2098119: Reemplace el sistema de contexto config con soporte incorporado para locales y anulaciones basadas en eventos únicos.

La información histórica/obsoleta puede encontrarse en #1646580: Implementación de eventos y escuchas para configuración y ámbitos de almacenamiento para configuración localizada donde se presentó inicialmente el sistema de anulaciones de configuración., así como #1763640: Introducir contexto de configuración para hacer la configuración original y otras anulaciones accesibles, con acceso contextual. y otras anulaciones significativas añadidas para el trabajo contextual. Las anulaciones específicas de idioma fueron añadidas posteriormente en #2020361: Crear LanguageConfigContext para activar anulaciones de configuración basadas en idioma.