Plupload integration
Provides Drupal integration for the Plupload JavaScript library, enabling multiple file uploads through a Form API element that other modules can use.
plupload
Install
composer require 'drupal/plupload:^2.2'
composer require 'drupal/plupload:^2.1'
Overview
The Plupload integration module provides a bridge between Drupal's Form API and the Plupload JavaScript library, a GPL-licensed multiple file uploading tool. This module does not provide end-user functionality directly; instead, it offers a #type => 'plupload' form element that developers can use in their modules and forms to enable advanced file upload capabilities.
Plupload supports multiple runtime environments including HTML5, Flash, Silverlight, and HTML4, automatically selecting the best available option based on the client's browser capabilities. This ensures maximum compatibility across different browsers and devices while providing modern features like drag-and-drop file selection, upload progress indicators, and chunked uploads for large files.
The module handles all the complexity of integrating with the Plupload library, including CSRF protection, secure file handling, temporary file management, and proper validation of uploaded files. It also integrates with Drupal's localization system to provide translated interface strings.
Features
- Provides a 'plupload' Form API element type for multiple file uploads
- Supports multiple upload runtimes: HTML5, Flash, Silverlight, and HTML4 fallback
- Automatic runtime selection based on browser capabilities
- Chunked file uploads for handling large files and avoiding server limitations
- Client-side file extension filtering with server-side validation
- Configurable upload validators using Drupal's file validation system
- Autoupload feature that starts uploading immediately after file selection
- Autosubmit feature that automatically submits the form after upload completion
- Custom event callbacks for Plupload events (FilesAdded, UploadComplete, etc.)
- Drag-and-drop file selection support in compatible browsers
- Upload progress indication with visual feedback
- CSRF token protection for secure upload handling
- Automatic .htaccess protection for temporary upload directory
- File name sanitization and transliteration for security
- Integration with Drupal's locale system for internationalized interface strings
- Configurable temporary upload location for high-availability environments
Use Cases
Multiple file upload in custom forms
Use the plupload element in custom module forms to allow users to upload multiple files at once. Define the element with '#type' => 'plupload', specify upload validators for allowed extensions, and handle the uploaded files in your form's submit handler by moving them from the temporary location to their final destination.
Large file uploads with chunking
For uploading large files that exceed PHP's upload_max_filesize or post_max_size limits, Plupload automatically chunks the upload into smaller pieces. Configure chunk_size in #plupload_settings to control the chunk size, typically set to match or be smaller than post_max_size.
Automatic upload and form submission
Create a streamlined upload experience by setting '#autoupload' => TRUE to start uploading immediately when files are added, and '#autosubmit' => TRUE to automatically submit the form when all uploads complete. Use '#submit_element' to specify which submit button to trigger.
Custom upload validation
Define custom file validation by specifying validators in '#upload_validators'. Use built-in validators like 'FileExtension' for extension checking, or create custom validation constraint plugins for specific requirements like image dimensions or file content validation.
Event-driven upload handling
Implement custom JavaScript callbacks for Plupload events using '#event_callbacks'. Listen to events like FilesAdded, UploadProgress, UploadComplete, or Error to create custom UI behaviors, progress indicators, or error handling.
Tips
- Always remove the 'examples' folder from the Plupload library after installation to prevent security vulnerabilities.
- Use '#upload_validators' to restrict allowed file types on both client and server side.
- For high-availability environments with multiple web servers, configure plupload.settings.temporary_uri to point to a shared storage location.
- The autoupload and autosubmit features work together - autoupload starts the upload automatically, and autosubmit triggers form submission when complete.
- When processing uploaded files in your submit handler, use the 'tmppath' key to get the full path to the temporary file, then move it to your desired destination.
- File names are automatically transliterated and sanitized to prevent directory traversal and other security issues.
- The module uses CSRF tokens to protect the upload endpoint - this happens automatically and requires no additional configuration.
Technical Details
Hooks 1
hook_library_info_alter
Alters the Plupload library definition to add dynamic settings such as max_file_size based on PHP configuration, chunk_size based on post_max_size, and conditionally includes the i18n.js file when the locale module is enabled.
Security Notes 6
- The Plupload library's examples folder must be removed after installation as it can expose security vulnerabilities. See https://drupal.org/node/1895328 for details.
- Uploaded files are temporarily stored in a protected directory with .htaccess rules preventing direct access.
- CSRF token validation is enforced on the upload endpoint to prevent cross-site request forgery attacks.
- File names are sanitized to prevent directory traversal attacks and dangerous file extensions are automatically renamed with .txt suffix when insecure uploads are disabled.
- Temporary files use .tmp extension regardless of the original file extension to prevent execution of uploaded scripts.
- Server-side validation is always performed even when client-side validation is enabled - never rely solely on client-side validation.