Migrate Spreadsheet
Proporciona un plugin de origen de migración para importar datos desde archivos de hojas de cálculo utilizando la biblioteca PhpOffice/PhpSpreadsheet.
migrate_spreadsheet
Instalar
composer require 'drupal/migrate_spreadsheet:^2.2'
composer require 'drupal/migrate_spreadsheet:^2.0'
Overview
Migrate Spreadsheet es un módulo de migración de Drupal que permite importar datos desde varios formatos de archivos de hojas de cálculo hacia Drupal. Proporciona un potente y flexible plugin de origen de migración que aprovecha la biblioteca PhpOffice/PhpSpreadsheet para leer y analizar archivos de hojas de cálculo.
El módulo soporta una amplia gama de formatos de hojas de cálculo incluyendo Open Document Format (.ods), formatos de Microsoft Excel (.xls, .xlsx), CSV, SpreadsheetML (.xml) y archivos SYLK (.slk). Ofrece un control detallado sobre la extracción de datos a través de opciones de configuración para especificar el origen de datos, filas de encabezado, selección de columnas y definiciones de clave primaria.
El plugin maneja el formato interno de fechas de Excel proporcionando integración con las utilidades de conversión de fechas de PhpSpreadsheet, permitiendo una migración fluida de valores de fecha y hora. La arquitectura basada en iteradores procesa eficientemente hojas de cálculo grandes mientras mantiene un bajo consumo de memoria.
Features
- Plugin de origen de migración (id: 'spreadsheet') para importar datos desde archivos de hojas de cálculo
- Soporte para múltiples formatos de archivo: Open Document Format (.ods), Office Open XML (.xlsx), BIFF 8 (.xls), BIFF 5 (.xls), SpreadsheetML (.xml), SYLK (.slk) y CSV
- Origen de datos configurable con notación de referencia de celda (ej., A2, B3) para especificar dónde comienzan los datos
- Configuración flexible de fila de encabezado para mapear nombres de columnas desde los encabezados de la hoja de cálculo
- Importación selectiva de columnas - especifica exactamente qué columnas extraer de la hoja de cálculo
- Soporte de clave primaria compuesta con definiciones de esquema de almacenamiento de campos
- Pseudo-columna de índice de fila para usar la posición de fila como clave primaria o campo de datos adicional
- Soporte de cálculo de fórmulas - los valores de celdas calculados se resuelven automáticamente
- Soporte de stream wrapper para rutas de archivos, permitiendo lectura desde varios backends de almacenamiento
- Procesamiento eficiente basado en iteradores con caché interno para manejo de archivos grandes
- Soporte de conversión de fecha/hora usando el método excelToTimestamp() de PhpSpreadsheet
Use Cases
Importar datos de usuarios desde una hoja de cálculo Excel
Migrar cuentas de usuario desde un archivo Excel corporativo que contiene información de empleados. Configurar el origen de la hoja de cálculo para mapear columnas como 'ID de Empleado', 'Email', 'Nombre', 'Apellido' a campos de usuario de Drupal. Usar el ID de Empleado como clave primaria para rastrear el estado de la migración y habilitar la reversión.
Migrar catálogo de productos desde CSV
Importar datos de productos desde una exportación CSV de una plataforma de comercio electrónico o sistema ERP. Mapear columnas de productos a campos de Commerce Product incluyendo SKU, título, descripción y precio. Manejar variaciones de productos usando claves compuestas.
Migración de contenido desde LibreOffice Calc (.ods)
Migrar contenido heredado almacenado en hojas de cálculo de LibreOffice Calc hacia tipos de contenido de Drupal. Útil para organizaciones que están en transición de la gestión manual de contenido en hojas de cálculo a un CMS estructurado.
Importar términos de taxonomía con jerarquías
Construir un vocabulario de taxonomía desde una hoja de cálculo que contiene datos de categorías. Usar el índice de fila como ID del término y mapear relaciones padre desde una columna 'Padre' para establecer jerarquías de términos.
Sincronización periódica de datos
Configurar importaciones recurrentes desde hojas de cálculo exportadas regularmente (ej., actualizaciones de inventario, cambios de precios). El sistema de clave primaria permite actualizar contenido existente en lugar de crear duplicados.
Manejo de campos de fecha desde Excel
Migrar valores de fecha y datetime desde archivos Excel donde las fechas se almacenan como números de serie. Usar el callback Date::excelToTimestamp() de PhpSpreadsheet en el pipeline de proceso para convertir el formato de fecha de Excel a timestamps Unix, luego opcionalmente formatear al formato de cadena de fecha deseado.
Tips
- Siempre especifica la configuración 'columns' para limitar qué columnas se procesan - esto mejora el rendimiento y la claridad
- Cuando las hojas de cálculo no tienen un identificador único natural, usa 'row_index_column' para generar una clave posicional
- Excel almacena las fechas como valores numéricos (días desde 1900-01-01). Usa el plugin de proceso callback con PhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestamp para convertirlas
- La configuración 'origin' excluye la fila de encabezado - si tu encabezado está en la fila 1 y los datos comienzan en la fila 2, establece origin a 'A2'
- Para archivos CSV, el nombre de la hoja de trabajo típicamente debe ser el nombre del archivo sin extensión o simplemente usar cualquier cadena ya que PhpSpreadsheet lo maneja
- El iterador calcula los valores de fórmulas automáticamente - referencias de celda como '=A1+B1' devolverán el resultado calculado
- Usa stream wrappers en la ruta 'file' (ej., 'private://imports/data.xlsx') para leer desde directorios no públicos
- Al migrar hojas de cálculo grandes, el módulo lee datos eficientemente fila por fila en lugar de cargar todo el archivo en memoria
Technical Details
Troubleshooting 7
Verifica que la ruta del archivo sea correcta. Las rutas pueden ser relativas a la raíz de Drupal o absolutas. Asegúrate de que el archivo tenga los permisos de lectura adecuados para el usuario del servidor web.
La configuración 'worksheet' es requerida. Especifica el nombre exacto de la hoja de trabajo tal como aparece en el archivo de hoja de cálculo (distingue mayúsculas y minúsculas).
Asegúrate de que el nombre de columna en la configuración 'columns' coincida exactamente con el valor de la celda de encabezado en la hoja de cálculo. Verifica si hay espacios en blanco al inicio o al final tanto en la configuración como en la hoja de cálculo.
Cuando no se definen 'keys', debes establecer 'row_index_column' para proporcionar un nombre para la pseudo-columna que se usará como clave primaria.
Cada valor de celda de encabezado debe ser único dentro de la fila de encabezado. Edita la hoja de cálculo de origen para asegurar que todas las celdas de encabezado tengan valores distintos.
Excel almacena las fechas internamente como números de serie. Agrega un plugin de proceso callback usando PhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestamp para convertir estos valores.
La referencia de celda de origen especificada está fuera del rango de datos de la hoja de trabajo. Verifica que las coordenadas de origen estén dentro de los límites de datos reales de tu hoja de cálculo.
Security Notes 3
- Asegúrate de que los archivos de hojas de cálculo se almacenen en ubicaciones seguras con permisos de archivo apropiados para prevenir acceso no autorizado a datos potencialmente sensibles
- Al usar stream wrappers para rutas de archivos, verifica que las ubicaciones configuradas no sean accesibles públicamente vía web
- Ten precaución al migrar datos desde fuentes de hojas de cálculo no confiables ya que pueden contener fórmulas maliciosas que podrían ser evaluadas