Integración de Plupload
Proporciona integración de Drupal con la biblioteca JavaScript Plupload, permitiendo la carga de múltiples archivos a través de un elemento de Form API que otros módulos pueden utilizar.
plupload
Install
composer require 'drupal/plupload:^2.2'
composer require 'drupal/plupload:^2.1'
Overview
El módulo de integración de Plupload proporciona un puente entre la Form API de Drupal y la biblioteca JavaScript Plupload, una herramienta de carga múltiple de archivos con licencia GPL. Este módulo no ofrece funcionalidad directa para el usuario final; en su lugar, proporciona un elemento de formulario #type => 'plupload' que los desarrolladores pueden usar en sus módulos y formularios para habilitar capacidades avanzadas de carga de archivos.
Plupload soporta múltiples entornos de ejecución incluyendo HTML5, Flash, Silverlight y HTML4, seleccionando automáticamente la mejor opción disponible según las capacidades del navegador del cliente. Esto garantiza la máxima compatibilidad entre diferentes navegadores y dispositivos mientras proporciona características modernas como selección de archivos mediante arrastrar y soltar, indicadores de progreso de carga y cargas fragmentadas para archivos grandes.
El módulo maneja toda la complejidad de la integración con la biblioteca Plupload, incluyendo protección CSRF, manejo seguro de archivos, gestión de archivos temporales y validación adecuada de los archivos subidos. También se integra con el sistema de localización de Drupal para proporcionar cadenas de interfaz traducidas.
Features
- Proporciona un tipo de elemento 'plupload' de Form API para carga múltiple de archivos
- Soporta múltiples entornos de ejecución: HTML5, Flash, Silverlight y respaldo HTML4
- Selección automática del entorno de ejecución basada en las capacidades del navegador
- Cargas fragmentadas de archivos para manejar archivos grandes y evitar limitaciones del servidor
- Filtrado de extensiones de archivo del lado del cliente con validación del lado del servidor
- Validadores de carga configurables usando el sistema de validación de archivos de Drupal
- Función de carga automática que comienza a subir inmediatamente después de seleccionar archivos
- Función de envío automático que envía automáticamente el formulario después de completar la carga
- Callbacks de eventos personalizados para eventos de Plupload (FilesAdded, UploadComplete, etc.)
- Soporte para selección de archivos mediante arrastrar y soltar en navegadores compatibles
- Indicación de progreso de carga con retroalimentación visual
- Protección con token CSRF para manejo seguro de cargas
- Protección automática con .htaccess para el directorio temporal de carga
- Sanitización y transliteración de nombres de archivo por seguridad
- Integración con el sistema de localización de Drupal para cadenas de interfaz internacionalizadas
- Ubicación temporal de carga configurable para entornos de alta disponibilidad
Use Cases
Carga múltiple de archivos en formularios personalizados
Use el elemento plupload en formularios de módulos personalizados para permitir a los usuarios cargar múltiples archivos a la vez. Defina el elemento con '#type' => 'plupload', especifique validadores de carga para extensiones permitidas, y maneje los archivos subidos en el handler de envío de su formulario moviéndolos desde la ubicación temporal a su destino final.
Cargas de archivos grandes con fragmentación
Para cargar archivos grandes que exceden los límites de upload_max_filesize o post_max_size de PHP, Plupload fragmenta automáticamente la carga en piezas más pequeñas. Configure chunk_size en #plupload_settings para controlar el tamaño del fragmento, típicamente configurado para igualar o ser menor que post_max_size.
Carga automática y envío de formulario
Cree una experiencia de carga optimizada configurando '#autoupload' => TRUE para comenzar a cargar inmediatamente cuando se agregan archivos, y '#autosubmit' => TRUE para enviar automáticamente el formulario cuando todas las cargas se completen. Use '#submit_element' para especificar qué botón de envío activar.
Validación personalizada de carga
Defina validación de archivos personalizada especificando validadores en '#upload_validators'. Use validadores integrados como 'FileExtension' para verificación de extensiones, o cree plugins de restricción de validación personalizados para requisitos específicos como dimensiones de imagen o validación de contenido de archivo.
Manejo de cargas basado en eventos
Implemente callbacks JavaScript personalizados para eventos de Plupload usando '#event_callbacks'. Escuche eventos como FilesAdded, UploadProgress, UploadComplete o Error para crear comportamientos de UI personalizados, indicadores de progreso o manejo de errores.
Tips
- Siempre elimine la carpeta 'examples' de la biblioteca Plupload después de la instalación para prevenir vulnerabilidades de seguridad.
- Use '#upload_validators' para restringir tipos de archivo permitidos tanto del lado del cliente como del servidor.
- Para entornos de alta disponibilidad con múltiples servidores web, configure plupload.settings.temporary_uri para apuntar a una ubicación de almacenamiento compartido.
- Las funciones autoupload y autosubmit trabajan juntas - autoupload inicia la carga automáticamente, y autosubmit activa el envío del formulario cuando se completa.
- Al procesar archivos subidos en su handler de envío, use la clave 'tmppath' para obtener la ruta completa al archivo temporal, luego muévalo a su destino deseado.
- Los nombres de archivo se transliteran y sanitizan automáticamente para prevenir traversal de directorio y otros problemas de seguridad.
- El módulo usa tokens CSRF para proteger el endpoint de carga - esto sucede automáticamente y no requiere configuración adicional.
Technical Details
Hooks 1
hook_library_info_alter
Modifica la definición de la biblioteca Plupload para agregar configuraciones dinámicas como max_file_size basado en la configuración de PHP, chunk_size basado en post_max_size, e incluye condicionalmente el archivo i18n.js cuando el módulo locale está habilitado.
Security Notes 6
- La carpeta examples de la biblioteca Plupload debe eliminarse después de la instalación ya que puede exponer vulnerabilidades de seguridad. Consulte https://drupal.org/node/1895328 para más detalles.
- Los archivos subidos se almacenan temporalmente en un directorio protegido con reglas .htaccess que previenen el acceso directo.
- La validación de tokens CSRF se aplica en el endpoint de carga para prevenir ataques de falsificación de solicitud entre sitios.
- Los nombres de archivo se sanitizan para prevenir ataques de traversal de directorio y las extensiones de archivo peligrosas se renombran automáticamente con sufijo .txt cuando las cargas inseguras están deshabilitadas.
- Los archivos temporales usan extensión .tmp independientemente de la extensión original del archivo para prevenir la ejecución de scripts subidos.
- La validación del lado del servidor siempre se realiza incluso cuando la validación del lado del cliente está habilitada - nunca confíe únicamente en la validación del lado del cliente.