API de configuración simple

Esta página describe la API para obtener y configurar datos de configuración para configuraciones simples. (Esto no es para la información almacenada en objetos de configuración.)

Datos de configuración

Cada módulo puede proporcionar una configuración por defecto. Por ejemplo, las configuraciones del modo de mantenimiento se definen en core/modules/system/config/install/system.maintenance.yml. En este archivo, la primera parte es un espacio de nombres que representa qué módulo proporcionó esta configuración (módulo system en este ejemplo), seguido de una subsistema (maintenance en este caso). El archivo debe estar en el directorio config/install. También debe contener un punto (“.”) en el nombre del archivo para validación en ConfigBase->validateName($name). Este archivo contiene el siguiente YAML:

message: '@site está actualmente en mantenimiento. Volveremos pronto. Gracias por su paciencia.'
langcode: en

La configuración también puede ser anidada, como en las configuraciones de rendimiento (system.performance.yml):

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

IMPORTANTE: las claves raíz deben ser un mapa

Los datos en la raíz de la configuración deben ser representados como un mapa, no como una secuencia impredecible. Por ejemplo, si almacena datos para cada tipo de entidad disponible, use una clave padre entity_type y añada claves raíz para cada tipo de entidad. Vea el ejemplo siguiente:

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

Si los tipos de entidad son la clave raíz, no es posible representar la configuración con una esquema. Además, Drupal core no podrá añadir información adicional cuando la configuración sea instalada como parte de un módulo (o tema).

Interacción con la configuración

Interactúa con estos archivos a través del objeto Config y creas una instancia del objeto Config llamando a la función config() con el nombre del archivo sin la extensión. La llamada a config devolverá una instancia de \Drupal\Core\Config\ImmutableConfig.

// Config inmutable (solo lectura).
$config = \Drupal::config('system.performance');

// Config mutable (lectura / escritura).
$config = \Drupal::service('config.factory')->getEditable('system.performance');

Con el objeto Config, puedes interactuar de varias maneras.

Lectura de configuración

La configuración se lee usando el método get(). Esto puede usarse de varias formas. Para leer un fragmento de la configuración, simplemente indica su clave.

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

Las llamadas a \Drupal::config() también pueden encadenarse.

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

Para leer configuraciones anidadas, separa las claves con el carácter “.”.

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

Puedes leer la configuración en cualquier nivel si debajo de tu nivel hay un arreglo anidado.

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

Esto devolverá un arreglo con dos claves — “enabled” y “max_age”.

Para devolver todos los datos en el objeto de configuración, simplemente llama a get() sin argumentos.

También puedes devolver todas las claves de configuración disponibles en el sistema, o solo las que comienzan con un prefijo específico ($prefix).

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

Escritura de configuración

Para modificar la configuración, necesitas obtener una instancia mutable \Drupal\Core\Config\Config llamando a getEditable() en la fábrica de configuración. Intentar cambiar o llamar a delete() / save() en una instancia de \Drupal\Core\Config\ImmutableConfig lanzará una excepción ImmutableConfigException.

Se hace así:

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

La configuración se modifica o añade usando el método set() y se guarda con save(). Ten en cuenta que la configuración debe guardarse explícitamente; simplemente establecer datos no guarda nada.

Guardas datos en el objeto de configuración igual que los lees, refiriéndote a claves y guardando los valores correspondientes. La sintaxis es similar a variable_set() de versiones anteriores de Drupal.

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

// Establece un valor escalar.
$config->set('cache.page.enabled', 1);

// Establece un arreglo de valores.
$page_cache_data = ['enabled' => 1, 'max_age' => 5];
$config->set('cache.page', $page_cache_data);

// Guarda tus datos en la base de datos.
$config->save();

El método set() también es encadenable, por lo que si solo necesitas cambiar un valor, puedes hacerlo en una sola línea de código.

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

Si deseas reemplazar todos los datos en el objeto de configuración, usa setData(). No puedes usar setData() para reemplazar solo un subconjunto de datos; si quieres reemplazar menos que todo el objeto, debes usar uno o varios llamados a set(). Al usar setData() debes proveer cada clave y valor en el formato de arreglo asociativo que devuelve get() sin argumentos. Para las opciones de rendimiento del sistema en system.performance.yml se verá así:

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

Eliminación de configuración

Valores individuales de configuración pueden borrarse con clear(), que también es encadenable.

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

En este ejemplo $page_cache_data devolverá un arreglo con una clave — “enabled” — porque “max_age” fue borrado.

Todo el conjunto de configuración puede eliminarse con delete().

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

Ten en cuenta que después de esto no debes llamar a save(), ya que creará una versión vacía del conjunto de configuración.

Buenas prácticas

Evita crear instancias del objeto de configuración múltiples veces dentro de la misma función, ya que esto reduce el rendimiento. El siguiente código crea innecesariamente dos instancias del objeto de configuración 'foo.bar'.

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

Es mejor crear la instancia una vez, guardarla en una variable y trabajar con ella durante el resto del código.

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

Inyección de valores de configuración en servicios

Los valores de configuración pueden inyectarse en tu servicio personalizado usando la fábrica de servicios.

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

El ejemplo fue adaptado de ¿Cómo inyectar valores de configuración en servicios?