Plupload統合
PluploadのJavaScriptライブラリとDrupalの統合を提供し、他のモジュールが使用できるForm API要素を通じて複数ファイルの同時アップロードを可能にします。
plupload
インストール
composer require 'drupal/plupload:^2.2'
composer require 'drupal/plupload:^2.1'
概要
Plupload統合モジュールは、DrupalのForm APIとGPLライセンスの複数ファイルアップロードツールであるPlupload JavaScriptライブラリの間の橋渡しを提供します。このモジュールはエンドユーザー向けの機能を直接提供するものではなく、開発者がモジュールやフォームで高度なファイルアップロード機能を実現するために使用できる#type => 'plupload'フォーム要素を提供します。
PluploadはHTML5、Flash、Silverlight、HTML4を含む複数のランタイム環境をサポートし、クライアントのブラウザ機能に基づいて最適なオプションを自動的に選択します。これにより、ドラッグ＆ドロップによるファイル選択、アップロード進捗インジケーター、大容量ファイル用の分割アップロードなどの最新機能を提供しながら、異なるブラウザやデバイス間で最大限の互換性を確保します。
このモジュールは、CSRF保護、安全なファイル処理、一時ファイル管理、アップロードされたファイルの適切な検証など、Pluploadライブラリとの統合に関するすべての複雑さを処理します。また、翻訳されたインターフェース文字列を提供するためにDrupalのローカライゼーションシステムとも統合しています。
Features
- 複数ファイルアップロード用の'plupload' Form API要素タイプを提供
- 複数のアップロードランタイムをサポート：HTML5、Flash、Silverlight、およびHTML4フォールバック
- ブラウザの機能に基づいた自動ランタイム選択
- 大容量ファイルの処理とサーバー制限の回避のための分割ファイルアップロード
- サーバーサイド検証を伴うクライアントサイドのファイル拡張子フィルタリング
- Drupalのファイル検証システムを使用した設定可能なアップロードバリデーター
- ファイル選択後すぐにアップロードを開始する自動アップロード機能
- アップロード完了後にフォームを自動送信する自動送信機能
- Pluploadイベント（FilesAdded、UploadCompleteなど）のカスタムイベントコールバック
- 対応ブラウザでのドラッグ＆ドロップによるファイル選択サポート
- 視覚的フィードバック付きのアップロード進捗表示
- 安全なアップロード処理のためのCSRFトークン保護
- 一時アップロードディレクトリの自動.htaccess保護
- セキュリティのためのファイル名サニタイズとトランスリタレーション
- 国際化されたインターフェース文字列のためのDrupalのLocaleシステムとの統合
- 高可用性環境向けの設定可能な一時アップロード場所
Use Cases
カスタムフォームでの複数ファイルアップロード
カスタムモジュールフォームでplupload要素を使用して、ユーザーが複数のファイルを一度にアップロードできるようにします。'#type' => 'plupload'で要素を定義し、許可される拡張子のアップロードバリデーターを指定し、フォームの送信ハンドラでアップロードされたファイルを一時的な場所から最終的な保存先に移動して処理します。
分割による大容量ファイルアップロード
PHPのupload_max_filesizeやpost_max_sizeの制限を超える大容量ファイルをアップロードする場合、Pluploadは自動的にアップロードを小さな断片に分割します。#plupload_settingsでchunk_sizeを設定して分割サイズを制御します。通常、post_max_sizeと同じかそれより小さく設定します。
自動アップロードとフォーム送信
'#autoupload' => TRUEを設定してファイル追加時にすぐにアップロードを開始し、'#autosubmit' => TRUEを設定してすべてのアップロード完了時にフォームを自動送信することで、効率的なアップロード体験を作成します。'#submit_element'を使用してトリガーする送信ボタンを指定します。
カスタムアップロード検証
'#upload_validators'でバリデーターを指定してカスタムファイル検証を定義します。拡張子チェックには'FileExtension'などの組み込みバリデーターを使用するか、画像サイズやファイル内容の検証など特定の要件に対応するカスタム検証制約プラグインを作成します。
イベント駆動型アップロード処理
'#event_callbacks'を使用してPluploadイベントのカスタムJavaScriptコールバックを実装します。FilesAdded、UploadProgress、UploadComplete、Errorなどのイベントをリッスンして、カスタムUI動作、進捗インジケーター、またはエラー処理を作成します。
Tips
- セキュリティ脆弱性を防ぐため、インストール後は必ずPluploadライブラリから「examples」フォルダを削除してください。
- '#upload_validators'を使用して、クライアントサイドとサーバーサイドの両方で許可されるファイルタイプを制限してください。
- 複数のWebサーバーがある高可用性環境では、plupload.settings.temporary_uriを共有ストレージの場所を指すように設定してください。
- autouploadとautosubmit機能は連携して動作します。autouploadは自動的にアップロードを開始し、autosubmitは完了時にフォーム送信をトリガーします。
- 送信ハンドラでアップロードされたファイルを処理する際は、'tmppath'キーを使用して一時ファイルへのフルパスを取得し、目的の保存先に移動してください。
- ファイル名は自動的にトランスリタレーションおよびサニタイズされ、ディレクトリトラバーサルやその他のセキュリティ問題を防止します。
- モジュールはアップロードエンドポイントを保護するためにCSRFトークンを使用します。これは自動的に行われ、追加の設定は必要ありません。
Technical Details
Hooks 1
hook_library_info_alter
Pluploadライブラリ定義を変更し、PHP設定に基づくmax_file_size、post_max_sizeに基づくchunk_sizeなどの動的設定を追加し、Localeモジュールが有効な場合はi18n.jsファイルを条件付きで含めます。
Security Notes 6
- Pluploadライブラリのexamplesフォルダはセキュリティ脆弱性を露出する可能性があるため、インストール後に削除する必要があります。詳細はhttps://drupal.org/node/1895328を参照してください。
- アップロードされたファイルは、直接アクセスを防ぐ.htaccessルールを持つ保護されたディレクトリに一時的に保存されます。
- クロスサイトリクエストフォージェリ攻撃を防ぐため、アップロードエンドポイントではCSRFトークン検証が強制されます。
- ファイル名はディレクトリトラバーサル攻撃を防ぐためにサニタイズされ、安全でないアップロードが無効な場合、危険なファイル拡張子は自動的に.txt接尾辞でリネームされます。
- 一時ファイルは、アップロードされたスクリプトの実行を防ぐため、元のファイル拡張子に関係なく.tmp拡張子を使用します。
- クライアントサイド検証が有効な場合でも、サーバーサイド検証は常に実行されます。クライアントサイド検証のみに依存しないでください。