Configuration Split
Permite dividir la configuración del sitio en conjuntos separados que pueden exportarse a diferentes directorios, fusionarse durante la importación y activarse/desactivarse por entorno.
config_split
Install
composer require 'drupal/config_split:^2.0'
Overview
Configuration Split extiende el sistema de gestión de configuración de Drupal permitiendo definir conjuntos de configuración que se exportarán a ubicaciones de almacenamiento separadas (directorios, colecciones o base de datos) durante la exportación, y se fusionarán al importar. Esto permite la gestión de configuración específica por entorno, donde módulos de desarrollo como Devel pueden estar habilitados en entornos locales pero excluidos de los despliegues en producción.
El módulo proporciona dos tipos de división: División Completa donde la configuración se mueve completamente al almacenamiento dividido y se elimina del directorio sync, y División Parcial donde la configuración permanece en sync pero las diferencias se almacenan como parches en el almacenamiento dividido. Las divisiones pueden activarse o desactivarse mediante overrides en settings.php o el state de Drupal, permitiendo un comportamiento flexible específico por entorno sin modificar la configuración exportada.
Configuration Split se integra perfectamente con los comandos de Drush para operaciones por línea de comandos y se conecta a los eventos de importación/exportación de configuración de Drupal para manejar de forma transparente la división y fusión durante las operaciones estándar de sincronización de configuración.
Features
- División completa: Mover la configuración completamente al almacenamiento dividido, eliminándola del directorio sync principal durante la exportación
- División parcial: Mantener la configuración en el directorio sync mientras se almacenan solo las diferencias como parches en el almacenamiento dividido
- Múltiples backends de almacenamiento: Almacenar la configuración dividida en carpetas del sistema de archivos, colecciones de configuración o tablas de base de datos
- Activación específica por entorno: Habilitar/deshabilitar divisiones mediante overrides en settings.php o el state de Drupal para control por entorno
- Filtrado de módulos: Dividir automáticamente toda la configuración relacionada con los módulos especificados, incluyendo la configuración dependiente
- Filtrado de temas: Dividir la configuración específica de temas (actualmente limitado)
- Soporte de comodines: Usar comodines (ej. views.view.*) para coincidir con múltiples elementos de configuración para dividir
- Divisiones apilables: Crear divisiones en capas donde las divisiones de mayor peso pueden modificar la configuración de divisiones de menor peso
- Parcheo de configuración: Actualizar automáticamente la configuración dependiente cuando los módulos se dividen
- Integración con Drush: Soporte completo por línea de comandos para operaciones de exportar, importar, activar, desactivar y override de estado
- Gestión mediante interfaz de usuario: Interfaz web para crear, editar y gestionar divisiones con capacidades de vista previa
- Visualización de diferencias: Ver las diferencias entre la configuración activa y la configuración dividida antes de importar
- Integración con config_readonly: Lista blanca automática de entradas de divisiones en base de datos para el módulo config_readonly
Use Cases
Gestión de módulos de desarrollo
Mantener módulos de desarrollo como Devel, Kint o Stage File Proxy habilitados localmente pero excluidos de producción. Crear una división 'development', agregar estos módulos a la división completa, y activar la división mediante settings.php en entornos de desarrollo: $config['config_split.config_split.development']['status'] = TRUE;
Configuración solo para producción
Mantener configuraciones específicas de producción como integración CDN, políticas de caché o configuración de analíticas separadas del desarrollo. Crear una división 'production' con configuración solo de producción en división completa, deshabilitada por defecto, y activar solo en servidores de producción.
Compartir configuración multi-sitio
Compartir una base de configuración común entre múltiples sitios mientras se permiten sobrescrituras específicas por sitio. Usar almacenamiento en colección para divisiones que deben viajar con la configuración principal, facilitando desplegar el mismo paquete de configuración a diferentes sitios con variaciones específicas por entorno.
Configuración de ramas de características
Usar divisiones parciales para gestionar cambios de configuración durante el desarrollo de características. La configuración base permanece en sync mientras los cambios específicos de la característica se almacenan como parches que pueden revisarse, fusionarse o descartarse fácilmente.
Configuración para diferentes entornos
Crear divisiones separadas para entornos de desarrollo, staging y producción. Usar peso para controlar el orden de procesamiento, y divisiones apilables para superponer cambios específicos de entorno sobre la configuración compartida. Ejemplo de estructura de carpetas: ../config/sync, ../config/dev, ../config/staging, ../config/production
Sobrescrituras de desarrollo local
Usar la función 'Activar solo localmente' para habilitar divisiones en máquinas de desarrollo individuales sin comprometer cambios de estado. Esto usa el state de Drupal en lugar de configuración, para que cada desarrollador pueda tener sus propias divisiones activas.
Tips
- Siempre usar rutas de carpeta fuera del directorio sync. Los directorios anidados causan conflictos durante la sincronización de configuración.
- Usar almacenamiento en colección cuando las divisiones deben incluirse en exportaciones/archivos de configuración (ej. para distribución).
- Usar almacenamiento en base de datos para configuración solo local que no debe compartirse entre entornos.
- Establecer prioridad de división en settings.php para ordenamiento predecible: $settings['config_split_priorities'] = ['production' => 100, 'development' => -100];
- Usar comodines en listas completas/parciales para coincidencia flexible: views.view.*, system.*, block.block.bartik_*
- La opción 'Activar solo localmente' es útil para probar divisiones sin afectar la configuración compartida.
- Cuando se usan divisiones apilables, recordar que las divisiones de mayor peso pueden modificar el contenido exportado de divisiones de menor peso.
- Revisar la página de Vista para cada división para ver Vista previa (lo que se exportaría) vs Exportado (lo que está actualmente almacenado).
- Para pipelines CI/CD, usar drush config-split:export después de drush cex, o confiar en el hook post-comando que se ejecuta automáticamente.
- Las divisiones parciales son ideales para configuración que debe existir en sync pero necesita valores específicos por entorno (como endpoints de API).
Technical Details
Admin Pages 8
/admin/config/development/configuration/config-split
Lista todas las configuraciones de división con su estado actual, estado por defecto y operaciones disponibles. Muestra si el estado está sobrescrito mediante settings.php o state.
/admin/config/development/configuration/config-split/add
Crear una nueva definición de división de configuración con ubicación de almacenamiento, módulos/temas a dividir y elementos de configuración específicos.
/admin/config/development/configuration/config-split/{config_split}
Ver la configuración de división incluyendo una vista previa de lo que se exportaría y lo que está actualmente en el almacenamiento dividido.
/admin/config/development/configuration/config-split/{config_split}/edit
Modificar una configuración de división existente. Mismo formulario que la página de Agregar con los valores actuales poblados.
/admin/config/development/configuration/config-split/{config_split}/activate
Activar una división inactiva importando su configuración desde el almacenamiento activo. Muestra un diff de los cambios que se realizarán.
/admin/config/development/configuration/config-split/{config_split}/deactivate
Desactivar una división activa eliminando su configuración del almacenamiento activo. Muestra un diff de los cambios.
/admin/config/development/configuration/config-split/{config_split}/import
Importar configuración desde el almacenamiento dividido a la configuración activa. Para divisiones inactivas, opcionalmente activa.
/admin/config/development/configuration/config-split/{config_split}/export
Exportar la configuración actual al almacenamiento dividido. Muestra las diferencias entre la vista previa actual y el almacenamiento existente.
Permissions 1
Hooks 1
hook_config_readonly_whitelist_patterns
Proporciona patrones para la lista blanca del módulo config_readonly. Configuration Split agrega automáticamente entradas de divisiones activas en base de datos a la lista blanca.
Drush Commands 5
drush config-split:export <split>
Exportar solo la configuración de la división especificada a su almacenamiento. La división debe estar activa.
drush config-split:import <split>
Importar configuración desde el almacenamiento de una división a la configuración activa.
drush config-split:activate <split>
Activar una división importando su configuración desde el almacenamiento activo y estableciéndola como activa.
drush config-split:deactivate <split>
Desactivar una división eliminando su configuración del almacenamiento activo.
drush config-split:status-override <split> [status]
Obtener o establecer el override de estado para una división mediante el state de Drupal. Útil para activación en tiempo de ejecución sin cambios de configuración.
Troubleshooting 7
Crear el directorio manualmente con los permisos apropiados. Asegurarse de que la ruta esté FUERA del directorio sync. Usar una estructura de directorio hermano como ../config/sync y ../config/dev.
Verificar que la división esté activa (comprobar el estado actual en la página de lista). Si está sobrescrita en settings.php, asegurarse de que el override establezca status a TRUE. Limpiar cachés después de cambiar settings.php.
Limpiar todas las cachés con drush cr después de modificar los overrides de settings.php. El sistema de override de configuración requiere limpieza de caché para tener efecto.
Esto ocurre cuando se importa configuración de una instalación diferente de Drupal. Asegurarse de que los directorios sync y de división contengan configuración de la misma instalación del sitio.
Comprobar la vista 'Exportado' en la página de división para ver qué hay en el almacenamiento dividido. Usar la vista de diff en los formularios de importar/exportar para previsualizar todos los cambios antes de aplicarlos.
Para divisiones parciales, las diferencias se calculan contra el almacenamiento sync (o almacenamiento compuesto para divisiones apilables). Asegurarse de que la configuración base en sync sea la esperada. Exportar a sync primero si es necesario.
Ajustar los valores de peso en las divisiones. Los pesos menores se procesan primero en exportación y últimos en importación. Para control explícito, establecer $settings['config_split_priorities'] en settings.php.
Security Notes 5
- El permiso 'administer configuration split' está marcado como 'restrict access' y solo debe otorgarse a administradores de confianza, ya que permite cambios significativos en la configuración del sitio.
- Las divisiones en almacenamiento de base de datos se incluyen en volcados de base de datos. Ser cauteloso al almacenar configuración sensible (claves API, credenciales) en divisiones de base de datos.
- Las carpetas de división se protegen automáticamente con archivos .htaccess (Apache) cuando se crean. Asegurarse de que el servidor web restrinja apropiadamente el acceso a los directorios de configuración.
- Cuando se usa almacenamiento en carpeta, asegurarse de que el directorio tenga permisos de sistema de archivos apropiados y no sea accesible por web.
- Los overrides de configuración en settings.php tienen precedencia sobre los overrides de state, proporcionando una forma segura de forzar el estado de división en producción.