Migrate Source CSV
Proporciona un plugin de origen CSV para la API Migrate de Drupal, permitiendo migraciones desde archivos CSV.
migrate_source_csv
Install
composer require 'drupal/migrate_source_csv:8.x-3.7'
composer require 'drupal/migrate_source_csv:8.x-3.4'
Overview
Migrate Source CSV es un módulo contribuido que proporciona un plugin de origen para la API Migrate de Drupal, permitiendo usar archivos CSV como fuentes de datos para migraciones. El módulo utiliza la biblioteca PHP League\CSV para capacidades robustas de análisis de CSV.
El módulo proporciona un plugin de origen altamente configurable que soporta varios formatos CSV incluyendo delimitadores personalizados, caracteres de encapsulamiento y secuencias de escape. Maneja archivos con o sin filas de encabezado y soporta tanto claves primarias simples como compuestas. El plugin también ofrece numeración opcional de registros para rastrear las posiciones de filas en el archivo fuente.
Este módulo es esencial para escenarios de migración de contenido donde los datos se exportan desde sistemas heredados o aplicaciones de hojas de cálculo en formato CSV. Se integra perfectamente con el framework de migración de Drupal y puede usarse con herramientas como Drush y el módulo Migrate Plus para una gestión mejorada de migraciones.
Features
- Plugin de origen CSV para la API Migrate de Drupal que lee datos desde archivos CSV
- Soporte para delimitadores CSV personalizados, caracteres de encapsulamiento y secuencias de escape para manejar varios formatos CSV
- Posición de fila de encabezado configurable con soporte para archivos sin encabezados
- Anulación de definición de campos permitiendo especificación manual de nombres y etiquetas de columnas
- Soporte de clave primaria compuesta usando múltiples columnas como identificadores únicos
- Numeración automática opcional de registros para rastrear posiciones de filas en archivos fuente
- Soporte de flujos de archivos permitiendo lectura desde varias fuentes de archivos
- Integración con la biblioteca League\CSV para análisis de CSV robusto y eficiente
- Soporte de origen vacío usando /dev/null para escenarios de migration_lookup
Use Cases
Migrar datos de usuarios desde una exportación de hoja de cálculo
Al migrar usuarios desde un sistema heredado que exporta datos como CSV, configure el plugin de origen csv con la ruta a su archivo de usuarios exportado. Establezca la columna de identificador único (como email o ID de usuario) como la configuración ids. Mapee las columnas CSV a los campos de usuario de Drupal en la sección process de su migración.
Importar catálogo de productos desde sistema externo
Para sitios de comercio electrónico, use el origen csv para importar datos de productos exportados desde sistemas de gestión de inventario. Configure delimitadores personalizados si la fuente usa formatos delimitados por pipes o tabulaciones. Use la configuración fields para proporcionar etiquetas legibles para documentación.
Migración de contenido con claves compuestas
Cuando los datos fuente usan múltiples columnas como clave compuesta (ej., código de idioma + ID de contenido), configure múltiples valores en el array ids. El plugin usará todas las columnas especificadas juntas para identificar únicamente cada registro fuente.
Procesar archivos sin encabezados
Para archivos CSV que carecen de fila de encabezado, establezca header_offset en null y use la configuración fields para definir nombres de columnas. Cada definición de campo requiere como mínimo una propiedad 'name' que se usará como identificador de columna en sus mapeos de proceso.
Extender para procesamiento personalizado de filas
Cree un plugin de origen personalizado que extienda la clase CSV para agregar lógica de preprocesamiento. Anule el método initializeIterator() para transformar, filtrar o producir filas adicionales. El módulo de prueba csv_source_yield_test demuestra este patrón.
Usar números de registro como identificadores
Cuando el CSV fuente carece de un identificador único natural, habilite create_record_number para generar números de fila secuenciales. Establezca este campo como parte de su configuración ids para usar la posición de fila como identificador de migración.
Tips
- Use rutas absolutas para archivos CSV en producción, o use hook_migration_plugins_alter() para construir rutas dinámicamente basándose en la ubicación del módulo.
- Para archivos CSV grandes, la biblioteca League\CSV maneja la memoria eficientemente a través de iteradores, pero considere dividir archivos muy grandes para facilitar la depuración.
- Pruebe las migraciones con un pequeño subconjunto de datos primero usando la opción --limit en drush migrate:import.
- Use el módulo Migrate Plus para características adicionales como grupos de migración, entidades de configuración y la interfaz de usuario de migración.
- Al depurar, la salida del método fields() muestra cómo el plugin de origen interpreta los nombres de columnas - verifique esto si los mapeos parecen incorrectos.
- La ruta /dev/null se maneja especialmente para proporcionar un origen vacío, útil para operaciones de migration_lookup que necesitan un origen pero realmente no migran datos.
- Considere usar stream wrappers de archivo (ej., public://, private://) para archivos CSV almacenados dentro del sistema de archivos de Drupal.
Technical Details
Hooks 1
hook_migration_plugins_alter
Puede usarse para alterar las definiciones de plugins de migración, como modificar la ruta de origen para migraciones CSV. El módulo de prueba demuestra este patrón para establecer rutas absolutas para archivos fuente CSV.
Troubleshooting 7
Asegúrese de que su YAML de migración incluya una clave 'path' bajo la configuración de origen apuntando a una ruta absoluta o URI de flujo de archivo válido para su archivo CSV.
Agregue un array 'ids' a su configuración de origen conteniendo el(los) nombre(s) de columna que identifican únicamente cada fila. Ejemplo: ids: [id] o ids: [language, content_id]
Asegúrese de que estas opciones de configuración sean exactamente un carácter. Los delimitadores de múltiples caracteres no son soportados por la biblioteca CSV subyacente.
Verifique que la ruta del archivo sea correcta y que el archivo exista. Use rutas absolutas o stream wrappers de Drupal. Verifique los permisos del archivo.
Verifique los permisos del archivo, asegúrese de que el usuario del servidor web tenga acceso de lectura al archivo CSV.
Si usa una fila de encabezado, verifique que header_offset esté configurado correctamente (0 para la primera fila). Si header_offset es incorrecto, los nombres de columnas serán valores de datos en lugar de encabezados. Use la configuración fields para anular nombres de columnas si es necesario.
Verifique que la configuración del delimitador coincida con el formato de su archivo. Los problemas comunes incluyen usar delimitador de coma para archivos separados por tabulaciones o viceversa.
Security Notes 3
- Asegúrese de que los archivos CSV fuente no sean accesibles vía URLs web si contienen datos sensibles. Almacene los archivos fuera de la raíz web o use el stream wrapper private://.
- Valide y sanee los datos durante la fase de proceso de las migraciones, especialmente para archivos CSV proporcionados por usuarios.
- Sea cauteloso con la configuración path - acepta rutas de archivos y flujos, así que restrinja quién puede crear o modificar configuraciones de migración en producción.