Las importaciones masivas en PHP suelen comenzar con un CSV enviado por un cliente, un export de un proveedor o una extracción de un sistema heredado. El riesgo aparece cuando se tratan como una simple lectura de archivo seguida de inserciones en base de datos. Una fila puede tener formato válido y, aun así, crear un duplicado, incumplir una regla comercial, sobrescribir información vigente o disparar un efecto externo dos veces.
Una importación debe diseñarse como un proceso operativo con un ciclo definido: recepción, análisis, validación, previsualización, confirmación, ejecución, revisión y recuperación. Este enfoque permite que producto entienda qué se incorporará, que operaciones intervenga ante excepciones y que tecnología limite el impacto de datos defectuosos.
Tratar la importación como un proceso de negocio
El archivo no es la fuente de verdad por sí mismo: es una solicitud para modificar el estado de la aplicación. Por ello, conviene crear una entidad de importación con un identificador propio, usuario o sistema que la inició, fecha de recepción, tipo de datos, versión del contrato, archivo o referencia segura al mismo, estado global y resumen de resultados.
Los estados globales deben expresar una situación operable, no sólo un booleano. Por ejemplo: recibido, analizado, pendiente de confirmación, en proceso, completado, completado con incidencias, detenido o cancelado. Una importación con 9.800 filas aceptadas y 200 rechazadas no es necesariamente un fracaso; puede ser una ejecución completada con incidencias si las filas rechazadas están aisladas y explicadas.
También hay que decidir qué consecuencias pertenecen a la carga. Crear un pedido, actualizar un catálogo o dar de alta contactos puede requerir cálculos, auditoría o notificaciones. Separar la persistencia principal de efectos secundarios reduce el riesgo de que un reintento envíe mensajes repetidos o ejecute integraciones de forma no controlada.
Definir un contrato de entrada antes de aceptar archivos
El contrato de importación especifica qué se espera recibir y cómo se interpretará. Debe incluir formato permitido, codificación, separador, cabeceras, tipos de dato, campos obligatorios, formato de fechas, reglas de normalización, límites de tamaño y número máximo de filas. Si se aceptan hojas de cálculo, hay que definir también la hoja relevante y cómo se tratarán las celdas vacías, fórmulas y valores convertidos automáticamente.
Los campos que conectan el origen con el destino merecen especial atención. Un identificador externo estable, como el código de cliente en el sistema de origen, es preferible a usar el número de línea o un nombre como referencia. Debe aclararse si ese identificador crea un registro, actualiza uno existente o si ambas operaciones están permitidas.
Separar capas de validación
La validación estructural responde a preguntas mecánicas: ¿el archivo se puede leer?, ¿existen las columnas requeridas?, ¿la fecha tiene un formato admitido?, ¿el importe es numérico?, ¿la fila respeta el límite de longitud? Esta capa debe detectar pronto problemas que impiden interpretar los datos.
La validación de dominio aplica reglas del negocio: un estado puede no estar permitido, una fecha de baja no puede preceder a la de alta, un porcentaje debe permanecer dentro de su rango o una combinación de campos puede resultar incompatible. Finalmente, las comprobaciones contra datos existentes verifican referencias, permisos, unicidad y transiciones permitidas. Por ejemplo, que un código de proveedor exista, que el usuario pueda operar sobre esa organización o que un registro no esté bloqueado.
Esta separación mejora los mensajes y el diagnóstico. No es lo mismo informar de una columna ausente que de una referencia inexistente o de un cambio no autorizado. Además, las reglas de dominio deben reutilizarse desde la aplicación y desde el importador para evitar que la carga se convierta en un atajo que elude controles normales.
Previsualizar cambios y confirmar una intención explícita
La previsualización no debe prometer una ejecución exacta si los datos pueden cambiar entre el análisis y la confirmación, pero sí debe ofrecer una estimación verificable. Muestre el total de filas leídas, filas válidas, filas con advertencias, filas rechazadas, altas previstas, actualizaciones previstas y registros que no sufrirán cambios.
Las advertencias sirven para casos que requieren atención, pero no invalidan automáticamente una fila: por ejemplo, un teléfono normalizado, una descripción truncada según una regla conocida o un campo opcional vacío. Las advertencias no deben ocultar rechazos. Cada resultado necesita un código estable, un mensaje comprensible y, cuando sea seguro, el valor recibido y el valor normalizado.
La confirmación debe asociarse a una versión concreta del análisis. Si el usuario sustituye el archivo, corrige filas en una interfaz o cambia parámetros relevantes, el sistema debe invalidar la previsualización anterior y exigir un nuevo análisis. Así se evita confirmar un resumen que ya no representa la carga real.
Procesar por lotes sin estados ambiguos
Procesar todas las filas dentro de una única transacción parece seguro, pero puede mantener bloqueos durante demasiado tiempo, exceder límites de ejecución o convertir un fallo puntual en una reversión costosa. Procesar una fila por transacción, en cambio, puede generar demasiada sobrecarga y dificulta coordinar operaciones relacionadas.
La unidad de trabajo debe elegirse según la dependencia entre registros, el volumen y el coste de revertir. En muchos casos, un lote pequeño y acotado permite confirmar cambios de forma progresiva. Cada lote debe registrar inicio, finalización, número de filas tratadas y resultado. El trabajador debe poder retomarse sin depender de una sesión HTTP abierta: la carga se confirma desde la interfaz, pero su ejecución se realiza como tarea en segundo plano.
Evite mantener archivos completos en memoria. Lea de forma secuencial, normalice cada fila y almacene una representación de trabajo o un resultado de validación cuando sea necesario para auditar y reanudar. Imponga límites de tamaño, filas, tiempo y concurrencia. Un archivo inesperadamente grande no debe bloquear los recursos que atienden el trabajo diario.
para cada lote pendiente:
marcar lote como en_proceso
para cada fila del lote:
aplicar validaciones pendientes
persistir o enviar a cuarentena
registrar resultado por fila
confirmar lote
marcar lote como completadoSi un trabajador se interrumpe, no basta con volver a ejecutar el lote a ciegas. Se necesita un mecanismo de bloqueo con caducidad o recuperación, y el estado por fila debe permitir distinguir lo pendiente de lo ya confirmado.
Aislar errores en cuarentena y conservar evidencia
La cuarentena permite que las filas inválidas no bloqueen las correctas sin desaparecer del proceso. Una fila en cuarentena debe conservar el número o identificador de origen, los datos recibidos bajo controles de acceso, los datos normalizados si existen, códigos de error, momento de detección y el estado de revisión.
No todos los errores tienen el mismo tratamiento. Un archivo sin cabecera requerida es un error de archivo y puede detener el análisis completo. Una referencia a un proveedor inexistente puede ser un rechazo de fila. Una caída temporal de la base de datos o de una integración es un error técnico reintentable y no debe etiquetarse como defecto del dato.
La interfaz operativa debe permitir filtrar por motivo, exportar sólo las incidencias autorizadas y comprender qué corrección se espera. Corregir dentro de la aplicación puede ser útil para pocos casos; para muchos registros, suele ser más controlable descargar las incidencias, corregirlas en origen y presentar una nueva carga. En ambos casos, mantenga el historial: modificar una fila en cuarentena no debe borrar el valor original ni el motivo inicial.
Garantizar idempotencia y evitar duplicados
La idempotencia significa que repetir una operación con la misma intención no altera el resultado más de una vez. Es esencial porque los reintentos ocurren: se agota un tiempo de espera, un proceso se reinicia o un operador vuelve a confirmar ante una respuesta incierta.
Una clave de idempotencia puede construirse a partir del tipo de importación, la organización de destino y un identificador externo estable. Debe respaldarse con restricciones de unicidad en la base de datos cuando el modelo lo permita; comprobar primero y luego insertar no elimina las condiciones de carrera entre trabajadores concurrentes.
Para actualizaciones, defina una política explícita: sustituir campos, aplicar sólo valores no vacíos, rechazar conflictos o exigir una versión esperada del registro. La última opción ayuda a detectar que un usuario cambió el dato después de la previsualización. No use una huella del archivo como único mecanismo: un mismo contenido puede representar una intención distinta y un archivo corregido puede conservar muchas filas ya procesadas.
Trazabilidad, reintentos y recuperación selectiva
El resultado por fila es la pieza central para soporte y recuperación. Registre un estado como pendiente, procesada, rechazada, en cuarentena, reintento pendiente o omitida; el identificador externo; el lote; códigos de motivo; marcas de tiempo; y una referencia al registro creado o actualizado. Proteja datos personales y secretos: la trazabilidad debe ser suficiente para investigar, no una copia indiscriminada de información sensible en logs.
Los reintentos deben ser selectivos. Reintente automáticamente errores técnicos transitorios con límites y espera progresiva; no reintente indefinidamente una regla de dominio incumplida. Cuando se corrija una referencia faltante o un dato inválido, reprocese sólo las filas en cuarentena que correspondan. Cuando falle un lote, continúe desde las filas pendientes y use las ya procesadas como evidencia de progreso.
Antes de poner el flujo en producción, pruebe archivos vacíos, cabeceras alteradas, codificaciones inesperadas, duplicados dentro del mismo archivo, duplicados contra la base de datos, interrupciones entre lotes, reanudaciones y permisos insuficientes. Las importaciones masivas en PHP son confiables cuando su comportamiento ante el fallo está diseñado con la misma precisión que su camino correcto.
