File (Field) Paths
ファイルフィールドにトークンベースのファイルパスとファイル名のカスタマイズ機能を追加するモジュール。
filefield_paths
概要
File (Field) Pathsモジュールは、DrupalコアのFileモジュールやImageモジュール、その他のファイルアップロードモジュールの機能を拡張します。エンティティベースのトークンを使用して、アップロードされたファイルの保存先パスとファイル名を動的に設定できるようになります。
標準のDrupalでは、ファイルのアップロード先ディレクトリの設定に使用できるトークンは限られていますが、このモジュールを使用すると、エンティティID、タイトル、作成日時など、より多くのトークンを活用できます。これにより、アップロードされたファイルを自動的に整理・リネームし、ファイルシステムを整然と保つことができます。
また、既存のファイルを新しいパス設定に従って一括更新する「遡及更新（Retroactive update）」機能や、エンティティ保存時に自動的にファイルパスを更新する「アクティブ更新（Active updating）」機能も提供します。さらに、Redirectモジュールと連携して、ファイル移動時に自動的にリダイレクトを作成することも可能です。
Features
- トークンを使用したファイルパスの設定: エンティティのID、タイトル、日付などのトークンを使用して、ファイルの保存先ディレクトリを動的に設定できます。例えば、[node:created:custom:Y]/[node:created:custom:m]/のようなパターンで日付別にファイルを整理できます。
- トークンを使用したファイル名の設定: アップロードされたファイルのファイル名もトークンを使って動的に変更できます。元のファイル名を保持しながら、プレフィックスやサフィックスを追加することも可能です。
- クリーンアップオプション（スラッシュ除去）: トークンから生成された文字列に含まれるスラッシュ（/）を自動的に除去し、意図しないサブディレクトリの作成を防ぎます。
- Pathauto連携によるクリーンアップ: Pathautoモジュールがインストールされている場合、そのエイリアスクリーナー機能を使用して、ファイルパスやファイル名から不要な文字を除去し、URLに適した形式に変換します。
- トランスリタレーション: 非ローマ字（日本語、キリル文字など）をASCII文字に変換し、すべての環境で互換性のあるファイル名を生成します。
- 遡及更新（Retroactive update）: 既にアップロードされているファイルを、新しいパス設定に従って一括で移動・リネームします。バッチ処理で実行されるため、大量のファイルも効率的に処理できます。
- アクティブ更新（Active updating）: エンティティが保存されるたびに、添付ファイルのパスを自動的に更新します。エンティティのタイトルが変更された場合などに、ファイルパスも連動して更新されます。
- リダイレクト作成: Redirectモジュールと連携し、ファイルが移動された際に自動的にリダイレクトを作成します。これにより、古いURLへのリンクが切れることを防ぎます。
- オリジナルファイル名の保存: ファイルエンティティにoriginameフィールドを追加し、リネーム前の元のファイル名を保存します。トークン[file:ffp-name-only-original]や[file:ffp-extension-original]で参照できます。
- 一時ファイル保存場所の設定: ファイル処理前の一時保存場所を設定でき、セキュリティを考慮してtemporary://やprivate://の使用を推奨します。
Use Cases
日付ベースのファイル整理
大量のファイルをアップロードするサイトで、ファイルを年月別のディレクトリに自動整理します。File pathに「[node:created:custom:Y]/[node:created:custom:m]」を設定すると、2024年1月に作成されたノードのファイルは「2024/01/」ディレクトリに保存されます。これにより、サーバー上のファイルシステムが整理され、大量のファイルがあっても管理しやすくなります。
コンテンツタイトルベースのファイル名
アップロードされたファイルのファイル名を、関連するコンテンツのタイトルに基づいて自動リネームします。File nameに「[node:title]-[file:ffp-name-only-original].[file:ffp-extension-original]」を設定し、「Cleanup using Pathauto」を有効にすると、「製品紹介」というノードにアップロードされた「image1.jpg」は「seihin-shoukai-image1.jpg」のように変換されます。
多言語サイトでのファイル名の正規化
日本語や中国語など、非ASCII文字を含むファイル名をアップロードする多言語サイトで、「Transliterate」オプションを有効にしてファイル名をASCII文字に変換します。これにより、すべてのサーバー環境（特に日本語に対応していないシステム）でファイルが正しく処理されます。
カテゴリ/タクソノミー別のファイル整理
ファイルを関連するタクソノミー用語別に整理します。File pathに「[node:field_category:entity:name]」のようなトークンを使用すると、「ニュース」カテゴリのノードに添付されたファイルは「news/」ディレクトリに、「製品」カテゴリは「products/」ディレクトリに保存されます。
既存ファイルの一括再編成
サイトのファイル整理ルールを変更した場合、既存の何千ものファイルを新しいルールに従って再編成する必要があります。「Retroactive update」機能またはDrushコマンド「drush ffpu」を使用すると、バッチ処理で既存のすべてのファイルを新しいパス設定に移動できます。この機能は開発環境で十分にテストしてから本番環境で使用してください。
SEOフレンドリーなファイルURL
検索エンジン最適化のために、ファイルのURLを意味のあるものにします。Pathauto連携を使用してファイルパスをクリーンアップし、コンテンツのタイトルやカテゴリをパスに含めることで、「/sites/default/files/2024/01/img123.jpg」のような無意味なURLの代わりに「/sites/default/files/products/widget-pro/main-image.jpg」のような意味のあるURLを生成できます。
ファイル移動時のリンク切れ防止
「Active updating」と「Create Redirect」を組み合わせて使用すると、エンティティの更新によってファイルが移動された場合でも、古いURLへのリンクが機能し続けます。これは、外部サイトからリンクされているファイルや、検索エンジンにインデックスされているファイルURLの維持に特に重要です。
Tips
- Tokenモジュール、Pathautoモジュール、Redirectモジュールを一緒にインストールすることで、File (Field) Pathsのすべての機能を活用できます。
- 本番環境で「Retroactive update」や「Active updating」を有効にする前に、必ず開発環境で十分にテストしてください。
- 一時ファイル保存場所には、セキュリティのためtemporary://を使用することを強く推奨します。画像プレビューが必要な場合はprivate://を使用してください。
- ファイルURIは255文字に制限されています。長いトークンパターンを使用する場合は注意が必要です。パスが長すぎる場合は自動的に切り詰められます。
- 大量のファイルがあるサイトで「Retroactive update」を実行する場合は、サーバーのタイムアウト設定を確認し、必要に応じてDrushコマンドを使用してください。
- [file:ffp-name-only-original]と[file:ffp-extension-original]トークンを使用すると、ファイル名の構成要素を個別に操作できます。
- Pathautoのクリーンアップを使用する場合、Pathautoの設定（/admin/config/search/path/settings）で単語の区切り文字や大文字小文字の変換ルールを確認してください。
Technical Details
Admin Pages 2
/admin/config/media/file-system/filefield-paths
File (Field) Pathsモジュールのグローバル設定を行う画面です。主に、処理前のファイルが一時的に保存される場所を設定します。この設定は、個別のフィールド設定で上書きしない限り、すべてのファイルフィールドに適用されます。
/admin/structure/types/manage/[content-type]/fields/[field-name]
各ファイルフィールドの設定画面に、File (Field) Paths専用の設定セクションが追加されます。ここでトークンベースのファイルパスとファイル名、クリーンアップオプション、更新オプションなどを設定します。
Hooks 2
hook_filefield_paths_field_settings
File (Field) Paths設定フォームに表示するフィールドを定義するフックです。カスタムの設定項目を追加する場合に使用します。
hook_filefield_paths_process_file
アップロードされたファイルの処理をカスタマイズするフックです。エンティティ保存時にファイルに対して追加の処理を行う場合に使用します。
Drush Commands 1
drush filefield_paths:update
指定されたフィールドインスタンスのFile (Field) Pathsを遡及的に更新します。既存のすべてのファイルを新しいパス設定に従って移動・リネームします。
Troubleshooting 6
エンティティの作成時や更新時には、トークンの完全な値がまだDrupalに認識されていない場合があります。File (Field) Pathsは、まずファイルを一時的な場所にアップロードし、エンティティが保存されてトークン値が確定した後にファイルを適切な場所に移動します。エンティティを保存した後にファイルの場所を確認してください。
Retroactive updatesは、特定のバンドルのすべてのエンティティを処理し、ファイルを移動・リネームします。この操作は不可逆的であり、誤った設定でリンク切れを引き起こす可能性があります。必ず開発環境でテストしてから本番環境で使用してください。バックアップを取ることを強く推奨します。
サイトがプライベートファイルをサポートしている場合、一時ファイル保存場所にpublic://を使用すると、プライベートファイルが一時的に公開される可能性があります。/admin/config/media/file-system/filefield-paths でtemporary://またはprivate://に変更してください。
Tokenモジュールがインストールされていることを確認してください。また、使用しているトークンがそのエンティティタイプで利用可能か確認してください。フィールド設定画面の「Browse available tokens」リンクで利用可能なトークンを確認できます。
「Transliterate」オプションを有効にして、非ASCII文字をASCII文字に変換してください。これにより、すべてのサーバー環境でファイル名が正しく処理されます。
Drushコマンド「filefield_paths:update」を使用する際は、引数を正しい順序（entity_type、bundle_name、field_name）で指定してください。引数を省略すると対話モードで選択できます。また、「--all」オプションを使用するとすべてのフィールドを一括更新できます。
Security Notes 3
- 一時ファイル保存場所にpublic://を使用すると、プライベートファイルシステムで保護されるべきファイルが一時的に公開される可能性があります。サイトがプライベートファイルをサポートしている場合は、必ずtemporary://またはprivate://を使用してください。
- 「Retroactive update」および「Active updating」機能は、大量のファイル操作を行うため、予期しない結果を招く可能性があります。本番環境で使用する前に、必ずバックアップを取り、開発環境でテストしてください。
- トークンパターンにユーザー入力を含める場合は、悪意のあるファイルパスが作成されないよう注意してください。Pathautoのクリーンアップ機能を有効にすることで、危険な文字を除去できます。