Structure Sync
Exporta e importa contenido estructural (términos de taxonomía, bloques personalizados, enlaces de menú) como configuración para sincronización entre entornos.
structure_sync
Install
composer require 'drupal/structure_sync:^2.0'
Overview
Structure Sync aborda un desafío común en el desarrollo de Drupal: sincronizar contenido que es estructural por naturaleza pero se almacena como entidades de contenido en lugar de configuración. Mientras que el sistema de Configuration Management de Drupal maneja entidades de configuración como tipos de contenido y views, no gestiona entidades de contenido como términos de taxonomía, bloques personalizados y enlaces de menú.
Este módulo cierra esa brecha proporcionando tanto una interfaz administrativa como comandos Drush para exportar estos elementos de contenido estructural a un archivo de configuración (structure_sync.data.yml). Los datos exportados pueden luego ser confirmados en el control de versiones e importados en otros entornos, permitiendo contenido estructural consistente entre sitios de desarrollo, staging y producción.
El módulo soporta tres modos de importación diferentes: Full (crea nuevos elementos, actualiza los existentes, elimina elementos que no están en la configuración), Safe (solo crea nuevos elementos sin modificar o eliminar los existentes), y Force (elimina todos los elementos existentes y los recrea desde la configuración). Esta flexibilidad permite a los equipos elegir la estrategia de sincronización apropiada para su flujo de trabajo.
Features
- Exportar términos de taxonomía de todos o vocabularios seleccionados a configuración, incluyendo campos personalizados y relaciones jerárquicas padre-hijo
- Exportar bloques personalizados (entidades block_content) con todos sus valores de campo a configuración
- Exportar enlaces de menú con metadatos completos incluyendo opciones de enlace, pesos, estado expandido y relaciones padre
- Importar contenido con tres modos distintos: Full (sincronizar), Safe (solo aditivo), Force (recreación destructiva)
- Integración de comandos Drush para automatización de pipelines CI/CD y despliegues con scripts
- Exportación/importación selectiva permitiendo control granular sobre qué vocabularios, bloques o menús sincronizar
- Coincidencia de entidades basada en UUID asegura identificación consistente entre entornos
- Maneja campos de referencia a entidades en términos de taxonomía almacenando pares nombre/vocabulario en lugar de IDs
- Registro opcional de todas las operaciones de exportación/importación para pistas de auditoría
- Procesamiento por lotes para importaciones grandes para prevenir timeouts
- Limpieza automática de caché después de importaciones para asegurar que los cambios surtan efecto inmediatamente
Use Cases
Flujo de trabajo de despliegue multi-entorno
Cuando se desarrolla un sitio con múltiples entornos (local, desarrollo, staging, producción), use Structure Sync para asegurar que los términos de taxonomía, estructuras de menú y bloques reutilizables sean consistentes. En su entorno de desarrollo, cree y organice sus términos, menús y bloques, luego ejecute 'drush export:all' seguido de 'drush config:export'. Confirme el archivo structure_sync.data.yml resultante en su repositorio. En staging/producción, obtenga los cambios y ejecute 'drush config:import' seguido de 'drush import:all --choice=full' para sincronizar el contenido estructural.
Configuración inicial del sitio con estructura predefinida
Cuando se construye un nuevo sitio que requiere una estructura de taxonomía específica (ej., categorías, etiquetas, regiones), cree todos los términos en un sitio de desarrollo, expórtelos e inclúyalos en el perfil de instalación o configuración de su sitio. Las nuevas instalaciones tendrán la estructura de taxonomía completa disponible inmediatamente después de ejecutar la importación de configuración e importación de structure sync.
Staging de contenido con sincronización selectiva
Use el modo de importación Safe cuando quiera agregar nuevo contenido estructural desde desarrollo a producción sin afectar contenido existente que pueda haber sido modificado. Esto es útil cuando producción tiene términos adicionales o elementos de menú creados por editores de contenido que no deberían eliminarse.
Migración y clonación de sitios
Cuando se clona un sitio o se migra entre proveedores de hosting, Structure Sync asegura que el contenido estructural sea preservado y pueda ser restaurado. Exporte todo el contenido estructural antes de la migración, y después de configurar el nuevo entorno con la configuración, importe el contenido estructural para restaurar completamente la organización del sitio.
Integración de pipeline CI/CD
Integre Structure Sync en su pipeline de despliegue continuo. Después de que las importaciones de configuración se completen, ejecute 'drush import:all --choice=full' para asegurar que el contenido estructural se sincronice automáticamente. Esto elimina pasos manuales y asegura despliegues consistentes.
Colaboración en equipo con contenido estructural compartido
En entornos de desarrollo en equipo, Structure Sync permite a los miembros del equipo compartir estructuras de taxonomía, configuraciones de menú y bloques reutilizables a través del control de versiones. Cuando un desarrollador crea nuevos términos o elementos de menú necesarios para una característica, los exporta y confirma, y otros desarrolladores pueden importar para obtener la misma estructura.
Tips
- Siempre ejecute 'drush config:export' después de exportar contenido estructural para guardar la configuración structure_sync.data en archivos
- Use el modo de importación Safe cuando sincronice por primera vez a un sitio de producción para evitar eliminar accidentalmente contenido creado por usuarios
- Para sincronización completa, use el modo de importación Full que actualiza elementos existentes y elimina elementos que no están en la configuración
- El modo de importación Force es útil para reinicios de desarrollo pero debe usarse con extrema precaución en sitios de producción
- El orden de exportación e importación importa: las taxonomías generalmente deben importarse antes del contenido que las referencia
- Los bloques personalizados deben tener el tipo de bloque (bundle) ya configurado antes de la importación - esto se maneja mediante la importación regular de configuración
- Después de importar enlaces de menú, limpie las cachés para asegurar que los menús se muestren correctamente: drush cache:rebuild
- Considere habilitar el registro durante la configuración inicial para rastrear lo que el módulo está haciendo, luego deshabilitarlo para rendimiento en producción
- El módulo vacía todas las cachés automáticamente después de importaciones de taxonomía y enlaces de menú para asegurar que los cambios sean visibles
Technical Details
Admin Pages 4
/admin/structure/structure-sync/general
Configurar opciones globales para el módulo Structure Sync. Actualmente proporciona control sobre si las operaciones se registran en el watchdog de Drupal.
/admin/structure/structure-sync/taxonomies
Exportar e importar términos de taxonomía de todos los vocabularios. Soporta términos jerárquicos con relaciones padre-hijo y campos personalizados adjuntos a los términos.
/admin/structure/structure-sync/blocks
Exportar e importar contenido de bloques personalizados (entidades block_content). Maneja todos los campos adjuntos a tipos de bloque incluyendo contenido del cuerpo y campos personalizados.
/admin/structure/structure-sync/menu-links
Exportar e importar elementos de contenido de enlaces de menú. Preserva la jerarquía del menú, opciones de enlace, pesos y estados habilitado/expandido.
Permissions 1
Drush Commands 8
drush export:taxonomies
Exportar todos los términos de taxonomía a configuración. Exporta términos de todos los vocabularios con sus campos, jerarquía y metadatos.
drush import:taxonomies
Importar términos de taxonomía desde configuración. Solicita el estilo de importación (Full, Safe o Force) a menos que se especifique mediante opción.
drush export:blocks
Exportar todos los bloques personalizados (entidades block_content) a configuración incluyendo todos los valores de campo.
drush import:blocks
Importar bloques personalizados desde configuración. Solicita el estilo de importación a menos que se especifique mediante opción.
drush export:menus
Exportar todos los elementos de contenido de enlaces de menú a configuración con metadatos completos y jerarquía.
drush import:menus
Importar enlaces de menú desde configuración. Solicita el estilo de importación a menos que se especifique mediante opción.
drush export:all
Exportar todo el contenido estructural (taxonomías, bloques y enlaces de menú) a configuración en una operación.
drush import:all
Importar todo el contenido estructural (taxonomías, bloques y enlaces de menú) desde configuración. Solicita el estilo de importación una vez, se aplica a todos los tipos de contenido.
Troubleshooting 7
Debe exportar el contenido primero antes de importar. Ejecute 'drush export:taxonomies' (o blocks/menus) y luego 'drush config:export' para guardar los datos en archivos de configuración.
La configuración del vocabulario debe importarse antes de que los términos de taxonomía puedan ser importados. Ejecute 'drush config:import' primero para importar las definiciones de vocabulario, luego ejecute la importación de structure sync.
Los enlaces de menú con referencias padre requieren que el padre exista primero. Structure Sync maneja esto ordenando enlaces y creando padres antes que hijos. Si los problemas persisten, intente el estilo de importación Force para recrear toda la estructura del menú.
Solo se exportan los campos con nombres que comienzan con 'field_'. Los campos base y campos computados se excluyen. Asegúrese de que sus campos personalizados sigan la convención de nomenclatura de campos de Drupal.
Las importaciones grandes usan la API batch de Drupal para prevenir timeouts. Si usa la interfaz web y aún experimenta timeouts, use comandos Drush en su lugar, que no tienen limitaciones de timeout del servidor web.
El modo de importación Safe solo verifica términos existentes por combinación de nombre y vocabulario. Si necesita actualizar términos existentes, use el modo de importación Full en su lugar. El modo Force eliminará todos los términos existentes primero.
Structure Sync maneja los campos de referencia a términos de manera especial almacenando pares nombre/vid en lugar de TIDs. El módulo ejecuta una segunda pasada después de la importación inicial para resolver estas referencias. Si los problemas persisten, ejecute la importación nuevamente.
Security Notes 4
- El módulo requiere el permiso 'administer site configuration', que es un permiso poderoso que solo debe otorgarse a administradores de confianza
- La configuración exportada puede contener información sensible si los bloques contienen contenido privado - revise structure_sync.data.yml antes de confirmar en repositorios públicos
- El modo de importación Force elimina todo el contenido existente de ese tipo - use con extrema precaución y asegúrese de que existan respaldos
- El módulo confía en la integridad de los archivos de configuración - asegúrese de que su pipeline de despliegue valide la configuración antes de importar