<p>Definición y uso de tu propia configuración en Drupal 8</p>

Tema principal: definición de configuración propia

Puedes incluir configuración predeterminada en tu módulo, basándote en la funcionalidad de otros módulos (tipos de contenido, vistas, campos, formatos de texto, etc.).
Por ejemplo, el módulo de nodo proporciona configuración de tipos de contenido, por lo que en tu propio módulo puedes configurar un tipo de nodo predeterminado que puede venir con tu módulo.

Quizás quieras definir configuración para tus propios plugins, entidades y ajustes, que a su vez pueden ser utilizados por otros módulos, tal como se puede usar la configuración del tipo de contenido nodo. Drupal 8 facilita la definición de tu propia parte de configuración.

Archivo de configuración

Los archivos de configuración para tu módulo se encuentran en el subdirectorio config/install de tu módulo. Por ejemplo, /modules/example/config/install/example.settings.yml si tu módulo está en /modules/example. Puedes colocar aquí los archivos de configuración de tu módulo, usando el formato YAML.

Aunque no es obligatorio, se recomienda encarecidamente nombrar los archivos de configuración que defines para tu módulo usando el prefijo del nombre del módulo: por ejemplo, example.settings.yml para configuraciones. No nombres el archivo settings.yml o system.settings.yml, ya que esto podría generar conflictos con nombres de archivos en otros lugares. Si no sigues esta convención, comandos Drush como drush config:import pueden confundirse.

Esto también te permite proveer configuración para otros componentes, por ejemplo, un tipo de nodo de ejemplo, incluyendo la configuración predeterminada en tu módulo, donde el archivo de configuración es node.type.example_mytype.yml, identificando el archivo de configuración que será tratado como un tipo de nodo por el módulo nodo.

El nombre del archivo de configuración (excluyendo la extensión .yml) también se llama nombre de configuración en el sistema, y así es como puedes referirte a tu configuración desde la API PHP.

Estructura del archivo de configuración

El archivo de configuración debe usar el formato YAML. Puedes estructurar tu propio archivo de configuración como desees, no hay restricciones aparte del formato YAML para la estructura. Por ejemplo, si necesitas un parámetro para mostrar algo especial desde tu controlador de página, el archivo puede contener una clave message con un valor de cadena:

message: 'Hello'
langcode: 'en'

Se recomienda incluir el código de idioma del archivo bajo la clave langcode. Esto es usado por el sistema de idiomas para ofrecer el texto traducible para traducción. La clave langcode está reservada para este propósito y no debes usarla a nivel superior del archivo para otra cosa.

Para traducir la configuración, debe estar habilitado el módulo de traducción de configuración.

Para hacer que la configuración sea traducible, necesitas añadir dos archivos más:

- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml

El primero define el esquema de la configuración personalizada. Definiremos example.settings como un objeto config_object que contiene varios campos. Cada campo tiene un tipo: la definición del tipo base determina si el campo será traducible o no (ver core.data_types.schema.yml). Por ejemplo, path, que contiene una ruta interna de Drupal, no es traducible, mientras que text sí lo es.

# /modules/example/config/schema/example.schema.yml
example.settings:
  type: config_object
  label: 'Example config'
  mapping:
    message:
      type: text
      label: 'Message'

El segundo añade una referencia a /admin/config/regional/config-translation en el formulario de traducción correspondiente:

# /modules/example/example.config_translation.yml
example.admin.config:
  title: 'Example module'
  base_route_name: example.admin.config
  names:
    - example.settings

Por convención, la clave coincide con el nombre de la ruta base: example.admin.config es el nombre de la ruta al formulario de configuración administrativa de tu módulo. Los nombres listan todas las claves de configuración que se editan en el formulario, en este caso la configuración personalizada definida en el esquema anterior.

El archivo puede incluir listas más complejas y pares clave/valor en estructura arbórea. Por ejemplo, mira el archivo views.view.content.yml para un ejemplo de archivo de configuración con un poco de complejidad.

La traducción de configuración agrega automáticamente la pestaña "traducción de módulo" al formulario de configuración del módulo, pero puede no mostrarse si es la única pestaña disponible. Para añadir una pestaña "por defecto" al formulario de configuración, necesitas añadir otro archivo example.links.task.yml. (Ver Tareas locales definidas por módulo.)

# example.links.task.yml
example.admin.config:
  route_name: example.admin.config
  title: Settings
  base_route: example.admin.config

Uso de la configuración

Drupal 8 provee una API PHP para leer y escribir esta configuración. La forma más simple de usarla es el método estático Drupal::config():

$config = \Drupal::config('example.settings');
// Imprimirá 'Hello'.
print $config->get('message');
// Imprimirá 'en'.
print $config->get('langcode');

Si quieres editar la configuración y actualizarla con un nuevo valor, puedes usar el método \Drupal::service('config.factory')->getEditable():

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

// Establece y guarda un nuevo valor para el mensaje.
$config->set('message', 'Hi')->save();

// Ahora imprimirá 'Hi'.
print $config->get('message');

Véase también

• API de Configuración en Drupal 8