【第1回】管理ファイルとの使い分けと実装準備

本記事は、Drupal環境で非管理ファイル（Unmanaged Files）の活用方法を解説する全6回シリーズの第1弾です。

Drupalを長年利用されている方であれば、管理ファイル（Managed Files）についてはよくご存知でしょう。その場合は、「非管理ファイル（Unmanaged Files）の概要とメリット」のセクションまでスキップしていただいて構いません。

Drupalの管理ファイル（Managed Files）とは

管理ファイルとは、Drupalがデータベース内で追跡しているファイルのことです。これらは通常、UI経由でDrupalに追加され、コンテンツ作成時やフォーム送信時にアップロードされます。一般的には、ドキュメント、表計算ファイル、PDF、画像などのメディアファイルが該当します。

管理ファイルに関連するデータは、Drupalのデータベース内のfile_managedテーブルで追跡されます。テーブルの構造は以下の通りです：

これらのフィールドは、さまざまな基準に基づいてファイルを選択および処理するために必要なすべてのメタ情報を提供します。

ご覧のとおり、このメタデータは、同じMIMEタイプや言語のファイルをすべて選択するなど、ファイル資産を細かく制御するために使用できます。メディアエンティティとの関係について疑問を持たれるかもしれません。たとえば、使用されている画像がイメージファイルではなくメディアファイルとして定義されている場合はどうなるでしょうか？メディアファイルは画像ファイルのスーパーセットです。つまり、メディアラッパーが指し示す管理ファイルであり、再利用を可能にします。例えば、Mediaエンティティとしてアップロードされた画像は、依然として管理ファイルとして保存されます。Mediaエンティティは、再利用性とメタデータを追加するラッパーであり、基盤となる管理ファイルを指し示します。

非管理ファイル（Unmanaged Files）の概要とメリット

簡単に言えば、非管理ファイルとは、Drupalによって管理されていないファイル、つまりDrupalがその存在を記録していないファイルのことです。もちろん、サーバーに保存されているファイルが完全に管理されていないわけではありません。サーバーのファイルシステムはそれを認識していますが、Drupalの文脈での議論においては、そのファイルは管理されていません。

本シリーズで学べる内容

管理ファイルを使用することで得られる多くの利点があるにもかかわらず、なぜDrupalにファイルを無視させたいのでしょうか？このチュートリアルでは、特定の状況で非管理ファイルを使用したい理由と、その方法についてのユースケースを通じて、1つの答えを提示します。

このシリーズを通じて学べる内容は以下の通りです：

• パート1 – ユースケース例の仕様、それを実現するための抽象化されたアーキテクチャ、および基盤の構築
• パート2 – 配置済みの非管理ファイルをランダムに選択できるファイルハンドラー
• パート3 – ブロックのプリプロセス関数におけるTwigフレンドリーな変数
• パート4 – カスタムモジュールによる再利用可能なブロックプラグイン
• パート5 – Twig拡張機能
• パート6 – 選択ルール（1つの地域から1つ以上の画像を選択しない）を実装するための追加のファイル処理ロジック

実装するブロックの仕様

最終的に、ホームページ用のブロックを作成します。このチュートリアルでは、ブロックの内容を生成することに焦点を当てます。ブロックの仕様は以下の通りです：

• 3つの国の地図アウトライン画像を表示する
• 画像はランダムに選択される
• 画像は大陸または海洋の地域ごとに分類して保存される
• ランダム選択を行う際、同じ地域から複数の画像を選択してはならない

アーキテクチャ

詳細なアーキテクチャは、これからカバーする3つのソリューションバージョン間で多少異なります。3つのアプローチで異なるのは、カスタムモジュールからの出力が最終的にページ上でどのようにレンダリングされるかです。

非管理ファイルを選択する理由と判断基準

ファイルは国のアウトラインマップで、228枚あります。ここで、このチュートリアルの前提について振り返る良い機会です。非管理ファイルが最良の選択肢である場合とは、どのような時でしょうか？もしこれがそのような場合の1つであれば、なぜでしょうか？

それに答えるために、228枚の画像をDrupalに追加する場合、それらが管理ファイルになるとしたら、どのように処理するかを考えてみましょう。いくつかのオプションがあります：

• コンテンツタイプを作成し、ノードフォームのアップロードウィジェットを使用し、テキストリストフィールドまたはタクソノミータームを使用してカテゴリを設定する
• 階層的なタクソノミーボキャブラリーを作成し、タームフォームのアップロードウィジェットと、別のボキャブラリーからカテゴリを選択するためのアドオンフィールドを使用する
• 各画像のメディアアイテムを作成し、各画像のカテゴリフォルダーを識別できるコントリビュートモジュールを使用する
• 一括アップロード用のコントリビュートモジュールを使用する（ただし、カテゴリ要件に対応していない可能性がある）

ここでの共通点は「労力」です。これらのファイルを個別にアップロードするにしても、カテゴリを個別に設定するにしても、あるいはその両方を行うにしても、かなりの労力が必要です。さて、ファイルがノードコンテンツの一部である必要がある場合、あるいは労力を正当化する利点がある場合は、それで構いません。判断に従ってください。私たちのケースでは、管理ファイルで利用可能な情報を見直し、仕様の文脈でその価値を見てみましょう：

• ❌ fid – ランダム選択には不要
• ❌ uuid – 不要、ファイル名は一意
• ❌ langcode – サイトは多言語ではない
• ❌ filename – 非管理でも利用可能
• ❌ uri – 静的パスを使用
• ❌ filemime – すべてJPEG
• ❌ filesize – 不要
• ❌ status – すべての画像は永続的
• ❌ created – 関連性なし
• ❌ changed – 関連性なし

明らかに、ファイルが管理される際に利用可能になるファイル情報は、私たちの目的には重要ではありません。ただし、これらの情報が1つでも必要な場合は、管理ファイルを選択すべきです。今回の要件では不要であることがご理解いただけたと思います。

Drupalを使用し、Drupalが認識していないファイルを使用する場合、要件をどのように満たすのか疑問に思われるかもしれません。これは正当な質問であり、チュートリアルのパート5で回答されます。今のところ、後で使用するためにファイルをサーバーに配置しましょう。

以下は、すべての画像を含む私のローカルのツリー構造です：

segregated_maps
├── africa
├── antarctica
├── asia
├── australia
├── caribbean
├── central america
├── europe
├── mideast
├── north america
├── pacific islands
└── south america

管理ファイルの場合と同様に、この構造をサーバーに配置するためのオプションがいくつかあります：

• SSHを使用してサーバーにログインし、フォルダー構造を作成してから、scpを使用してファイルを移動する
• Filezillaのようなアプリケーションを使用して、フォルダー構造とファイルをSFTPで転送する
• rsyncを使用してファイルを移動し、フォルダー構造を作成する

私はオプション3を使用し、転送時にファイルを圧縮することで、非常に高速に処理します。segregated_mapsフォルダーをpublic://配下に配置します。

rsync -avz segregated_maps myuser@myserver:/path/to/target/

コマンドの内訳：

• -a – フォルダーを再帰的に処理し、パーミッションを保持
• -v – 詳細出力
• -z – 転送中に圧縮
• segregated_maps – ソースフォルダー（末尾のスラッシュなしでフォルダー名を保持）
• myuser@myserver – SSH ターゲット（IPまたはドメインも可）
• /path/to/target – 宛先パス

これにより、フォルダーツリーと画像がサーバーパスに配置されました。

次回（パート2）の内容

パート2では、コーディングを開始し、非管理ファイルハンドラーの機能的なプロトタイプを構築します。これはパート6で完成させます。

注：実際のコードを使って学習したい方のために、パート2でリンクを含めて、私のパブリックGitHubリポジトリにサンプルモジュールとサポートノートを公開します。

この記事は 「Unmanaged Files in Drupal (Part 1): When and Why to Use Them」の翻訳記事です。