Single Content Sync
Un módulo completo de exportación/importación de contenido que permite exportar cualquier entidad de contenido con todas sus referencias de entidad a formato YAML e importarlo a otro entorno.
single_content_sync
Install
composer require 'drupal/single_content_sync:^1.4'
Overview
Single Content Sync proporciona una forma fácil y potente de exportar e importar entidades de contenido entre diferentes entornos Drupal. El módulo exporta contenido en formato YAML, incluyendo todas las entidades referenciadas como media, términos de taxonomía, paragraphs y archivos.
Las capacidades principales incluyen exportar elementos de contenido individuales con su árbol completo de referencias de entidad, soporte para traducciones, operaciones de exportación masiva a través de Views Bulk Operations e importación automatizada durante despliegues mediante hook_update_N. El módulo cuenta con un sistema de plugins para extender el soporte a tipos de entidad y tipos de campo personalizados, junto con eventos para personalizar el proceso de exportación/importación.
El contenido se identifica por UUID, permitiendo que el contenido existente se actualice y que se cree contenido nuevo durante la importación. El módulo puede exportar como un único archivo YAML (con URLs de archivos como rutas absolutas) o como un archivo ZIP que contiene todos los recursos de archivos.
Features
- Exportar cualquier entidad de contenido (nodes, media, términos de taxonomía, blocks, etc.) a formato YAML con todas las referencias de entidad
- Importar contenido desde archivos YAML o ZIP a través de la interfaz de administración, programáticamente o mediante comandos Drush
- Exportación recursiva automática de todas las entidades referenciadas incluyendo paragraphs, media, archivos y términos de taxonomía
- Soporte de traducciones - exportar e importar todas las traducciones de contenido multilingüe
- Exportación masiva de múltiples elementos de contenido a la vez usando Views Bulk Operations
- La opción de exportación ZIP incluye todos los recursos de archivos (imágenes, documentos, vídeos)
- Sincronización de contenido basada en UUID - actualiza contenido existente o crea nuevo
- Validación de UUID del sitio para prevenir importaciones accidentales a entornos incorrectos
- Sistema de plugins para soporte de tipos de entidad y tipos de campo personalizados mediante plugins SingleContentSyncBaseFieldsProcessor y SingleContentSyncFieldProcessor
- Sistema de eventos (ExportEvent, ImportEvent, ExportFieldEvent, ImportFieldEvent) para personalizar el comportamiento de exportación/importación
- Comandos Drush para operaciones de exportación/importación desde línea de comandos
- Modos de exportación configurables para entidades embebidas y enlaces de menú (ninguno, stub o completo)
- Pestaña de exportación en las páginas canónicas de entidad para exportación rápida de una única entidad
- Soporte para secciones de Layout Builder, Paragraphs, Metatag, Webform y muchos tipos de campo contrib
- Manejo inteligente de enlaces internos en campos de texto formateado - resuelve referencias de entidad durante la importación
Use Cases
Sincronización de contenido entre entornos
Exporta contenido desde un entorno de desarrollo o staging e impórtalo a producción. Usa la opción de exportación ZIP para incluir todos los archivos adjuntos. La verificación de UUID del sitio puede deshabilitarse al mover contenido entre diferentes instancias del sitio, o habilitarse para asegurar que el contenido solo se mueva entre entornos clonados.
Respaldo y restauración de contenido
Exporta elementos de contenido importantes como archivos YAML almacenados en control de versiones o almacenamiento de respaldo. El contenido puede restaurarse importando el archivo YAML, con el UUID asegurando que el contenido original se actualice en lugar de duplicarse.
Despliegue automatizado de contenido predeterminado
Almacena archivos YAML/ZIP de contenido en la carpeta assets de un módulo personalizado e impórtalos durante el despliegue usando hook_update_N o hook_deploy. Ejemplo: \Drupal::service('single_content_sync.importer')->importFromFile($module_path . '/assets/homepage.yml');
Sincronización de contenido multilingüe
Exporta contenido con la opción 'Incluir todas las traducciones' para capturar todas las versiones de idioma. Al importar, las traducciones se recrean manteniendo las mismas relaciones de idioma.
Exportación masiva de contenido mediante Views
Usa Views Bulk Operations con la acción 'Export content' para seleccionar y exportar múltiples elementos de contenido a la vez. Útil para exportar conjuntos específicos de contenido como todos los artículos de una categoría o todos los productos.
Migración de contenido desde otro sitio Drupal
Exporta contenido desde un sitio Drupal de origen e impórtalo a un sitio destino. Deshabilita la verificación de UUID del sitio al importar. El módulo maneja la resolución de referencias a Entity, creando entidades stub para referencias faltantes.
Sincronización de contenido basada en Drush para CI/CD
Usa los comandos drush content:export y drush content:import en pipelines de despliegue automatizado. Exporta contenido durante la fase de construcción e importa durante el despliegue, asegurando contenido consistente entre entornos.
Soporte para tipos de Entity personalizados
Implementa un plugin SingleContentSyncBaseFieldsProcessor para tipos de Entity personalizados para habilitar el soporte de exportación/importación. El plugin define cómo se exportan los Field base y se mapean durante la importación.
Soporte para tipos de Field personalizados
Implementa un plugin SingleContentSyncFieldProcessor para tipos de Field personalizados o contribuidos no soportados de forma predeterminada. El plugin maneja la transformación de valores de Field durante la exportación y la creación de Entity durante la importación.
Tips
- Usa la exportación ZIP cuando el contenido incluya archivos (imágenes, documentos) para asegurar que todos los assets se incluyan e importen correctamente.
- Habilita la verificación de UUID del sitio en producción para prevenir sobrescrituras accidentales de contenido desde entornos no clonados.
- Usa el modo de exportación 'stub' para Entity incrustadas para reducir el tamaño del archivo de exportación mientras mantienes la integridad de las referencias.
- Almacena los archivos YAML exportados en la carpeta assets de tu módulo personalizado para importación de contenido en tiempo de despliegue.
- Usa los comandos Drush con la opción --dry-run primero para previsualizar qué se exportará sin crear archivos.
- Suscríbete a ImportEvent para agregar lógica personalizada de validación o transformación antes de que se guarde el contenido.
- Usa la acción de exportación masiva con Views para exportar conjuntos de contenido filtrados (ej., todos los artículos publicados de 2024).
- Al crear plugins de procesador de Field personalizados, extiende SingleContentSyncFieldProcessorPluginBase para funcionalidad base.
- El editor YAML en los formularios de exportación/importación proporciona resaltado de sintaxis - úsalo para revisar rápidamente la estructura del contenido.
- Para migraciones complejas, considera combinar este módulo con Migrate del core para más control sobre el proceso.
Technical Details
Admin Pages 3
/admin/config/content/single-content-sync
Configura qué tipos de Entity y bundles pueden exportarse, establece el modo de exportación para Entities incrustadas y enlaces de menú, y configura el esquema de almacenamiento de archivos para las operaciones de importación/exportación.
/admin/content/import
Importa contenido desde otro entorno subiendo un archivo YAML o ZIP, o pegando contenido YAML directamente. El contenido se verifica por UUID: el contenido existente se actualiza y el contenido nuevo se crea.
/{entity_type}/{entity_id}/export
Exporta una Entity de contenido individual a formato YAML. El formulario muestra una vista previa del contenido exportado y proporciona opciones para descargar como archivo YAML o ZIP. Ruta dinámica disponible en todas las páginas canónicas de Entity de contenido.
Permissions 4
Hooks 4
hook_content_export_field_value_alter
Modifica el valor del campo durante la exportación. OBSOLETO en 1.4.0, use el plugin SingleContentSyncFieldProcessor o ExportFieldEvent en su lugar.
hook_content_export_entity_alter
Modifica los campos base de la entidad durante la exportación. OBSOLETO en 1.4.0, use el plugin SingleContentSyncBaseFieldsProcessor o ExportEvent en su lugar.
hook_content_import_entity_alter
Modifica la entidad durante la importación antes de guardarla. OBSOLETO en 1.4.0, use el plugin SingleContentSyncBaseFieldsProcessor o ImportEvent en su lugar.
hook_content_import_field_value_alter
Modifica el valor del campo durante la importación. OBSOLETO en 1.4.0, use el plugin SingleContentSyncFieldProcessor o ImportFieldEvent en su lugar.
Drush Commands 2
drush content:export
Exporta todo el contenido de un tipo de entidad dado. Por defecto exporta todos los nodes al directorio DRUPAL_ROOT/scs-export.
drush content:import
Importa contenido desde un archivo YAML o ZIP en la ruta especificada.
Troubleshooting 7
Esto ocurre cuando la verificación de UUID del sitio está habilitada y el contenido proviene de una instalación Drupal diferente. Deshabilita 'Site UUID check' en la configuración en /admin/config/content/single-content-sync, o exporta desde la misma instancia del sitio.
El tipo de Entity debe tener una plantilla de enlace de URL canónica. Verifica la página de configuración para asegurar que el tipo de Entity esté habilitado para exportación. Los tipos de Entity personalizados necesitan definir una plantilla de enlace 'canonical' en su definición de Entity.
Implementa un plugin SingleContentSyncBaseFieldsProcessor para tu tipo de Entity, o usa el suscriptor de eventos ExportEvent para agregar manejo personalizado de Field base. El módulo muestra una advertencia cuando los Field base no son exportables.
Asegúrate de que el Bundle de la Entity referenciada exista en el sitio destino. El módulo crea entidades stub para referencias faltantes, pero el Bundle debe estar definido. Verifica que todos los tipos de Field requeridos tengan plugins de procesador de Field apropiados.
Asegúrate de que el archivo ZIP no contenga un directorio padre adicional. Los archivos YAML deben estar en la raíz del ZIP, con los assets en una subcarpeta 'assets'. El ZIP debe ser creado por la función de exportación del módulo.
Al importar sin ZIP (solo YAML), los archivos se referencian por URL absoluta. Asegúrate de que las URLs de origen sean accesibles. Para transferencia de archivos locales, usa la exportación ZIP que incluye todos los archivos adjuntos.
Asegúrate de que el idioma destino esté habilitado en el sitio destino antes de importar. Verifica que la opción 'Include all translations' estaba habilitada durante la exportación. Verifica que el tipo de contenido tenga la traducción habilitada.
Security Notes 6
- Solo otorga el permiso 'export single content' a usuarios de confianza ya que el contenido exportado puede incluir datos sensibles de Field.
- Solo otorga el permiso 'import single content' a administradores de confianza ya que la importación puede crear/modificar cualquier contenido.
- Ten precaución al deshabilitar la verificación de UUID del sitio ya que permite importar contenido desde cualquier fuente.
- Los archivos YAML exportados pueden contener información sensible - almacénalos de forma segura y no los incluyas en repositorios públicos.
- El módulo no valida el contenido de los archivos durante la importación - asegúrate de que los archivos ZIP provengan de fuentes confiables.
- Las referencias de usuario en el contenido exportado usan direcciones de correo electrónico que pueden considerarse información de identificación personal (PII).