File Entity（フィールド追加可能なファイル）

Extends Drupal file entities to be fieldable and viewable, allowing files to be organized into types with custom fields, display modes, and formatters.

file_entity
64,407 sites
58
drupal.org
gui api field content
media file fieldable entity upload image audio video document Views token pathauto rest HAL
Drupal 9 Drupal 10 Drupal 11

インストール

Drupal 11, 10 v8.x-2.3
composer require 'drupal/file_entity:8.x-2.3'
Drupal 9 v8.x-2.0
composer require 'drupal/file_entity:8.x-2.0'

概要

File Entityは、Drupalコアのファイルエンティティを完全な機能を持つコンテンツエンティティに変換する包括的なモジュールです。Field UIを通じてファイルにカスタムフィールドを追加したり、MIMEタイプに基づいてファイルをタイプ（バンドル）別に整理したり、様々な表示モードやフィールドフォーマッターを使用して表示したりできます。

このモジュールは、画像、音声、動画、ドキュメント用の組み込みファイルタイプを提供し、アップロードされたファイルをMIMEタイプに基づいて自動的に分類します。HTML5の音声・動画フォーマッター、レスポンシブ画像サポート、動的リンクテキスト用のTokenサポート付きダウンロードリンクフォーマッターが含まれています。

File EntityはDrupalのエコシステムと深く統合されており、ファイル一覧とフィルタリング用のViews統合、動的alt/titleテキスト用のToken APIサポート、ファイルURLエイリアス用のオプションのPathauto統合、ヘッドレスDrupal実装用のREST/HAL APIノーマライザーを提供します。

Features

  • フィールド追加可能なファイルエンティティ - Field UIを使用して任意のDrupalフィールドタイプをファイルに追加可能
  • ファイルタイプバンドル（画像、音声、動画、ドキュメント）とMIMEタイプによる自動分類
  • 設定可能なMIMEタイプパターンを持つカスタムファイルタイプ
  • タイプ選択、保存先スキーム、フィールド設定を含むマルチステップファイルアップロードウィザード
  • コントロール、自動再生、ループオプション付きHTML5オーディオプレーヤーフォーマッター
  • コントロール、自動再生、ループ、ミュート、サイズ設定付きHTML5ビデオプレーヤーフォーマッター
  • レスポンシブ画像スタイルをサポートするレスポンシブ画像フォーマッター
  • Tokenをサポートするカスタマイズ可能なリンクテキスト付きダウンロードリンクフォーマッター
  • 人間が読みやすいファイルサイズを表示するファイルサイズフォーマッター
  • AJAXモーダルダイアログによるインラインファイル編集ウィジェット
  • アーカイブのアップロードと展開機能
  • 専用データベーステーブルでのファイルメタデータ保存（画像サイズなど）
  • ファイル所有者、タイプ、ストリームラッパーに基づく詳細なアクセス制御
  • ファイルタイプごとの動的パーミッション（自分の/すべての編集・削除・ダウンロード）
  • ファイル管理用のカスタムフィールド、フィルター、引数を含むViews統合
  • 画像の動的altおよびtitle属性用Token API統合
  • ファイルURLエイリアス用Pathauto統合
  • base64ファイルコンテンツを含むヘッドレスDrupal用RESTおよびHAL APIノーマライザー
  • 削除、永続化、一時化のための一括操作
  • 各ファイルの使用場所を表示するファイル使用状況追跡ビュー
  • ファイルタイプ、MIMEタイプ、表示モードに基づくテーマサジェスト

Use Cases

Media library with custom metadata

Use File Entity to create a rich media library where images have custom fields for photographer credits, copyright information, and licensing terms. Audio files can have fields for artist, album, and duration. Video files can store resolution, codec information, and transcripts.

Document management system

Implement a document management workflow where uploaded documents are automatically classified by type. Add fields for document version, approval status, department, and expiration date. Use Views to create filtered document listings by department or status.

Multi-format media display

Use the HTML5 audio and video formatters to display media files with native browser players. Configure autoplay, controls, and loop settings. For images, use responsive image formatters to serve optimally-sized images based on device viewport.

Secure file distribution

Store sensitive files in the private file system and use granular permissions to control access. Create file types for different sensitivity levels, each with specific download permissions. Track file usage to audit which content uses specific files.

Headless Drupal media API

Use the HAL/REST normalizers to expose file entities through a REST API. File content is automatically base64-encoded for transfer. Frontend applications can upload files by posting base64-encoded content through the API.

Bulk file import from archives

Use the archive upload functionality to import multiple files at once. Upload a ZIP file containing images, and File Entity will extract all files matching a regex pattern, creating individual file entities for each with automatic type classification.

Tips

  • Use token patterns like [file:field_image_alt_text:value] for dynamic alt text on images to improve accessibility and SEO.
  • Create custom file types for specific use cases (e.g., 'Podcast', 'Infographic') with dedicated fields and permissions.
  • Use the 'Skip' options in File settings to streamline the upload wizard for sites with single file types or storage locations.
  • Configure the 'Editable file' widget on file/image fields to allow inline editing without leaving the parent entity form.
  • Leverage the file usage view at /file/{fid}/usage to audit where files are being used before deletion.
  • For better performance, use the 'File Size' formatter for displaying file sizes instead of custom preprocessing.
  • When using responsive images, ensure the responsive image style is configured before selecting it in the formatter settings.

Technical Details

Admin Pages 11
File types /admin/structure/file-types

Manage file types (bundles) used to organize and classify files on your site. Each file type can match specific MIME types and have its own set of custom fields.

Add file type /admin/structure/file-types/add

Create a new file type by defining its label, machine name, description, and associated MIME types.

Edit file type /admin/structure/file-types/manage/{file_type}/edit

Modify an existing file type's settings including label, description, and MIME type associations.

File settings /admin/config/media/file-settings

Configure global file entity settings including upload limits, allowed extensions, default alt/title attributes, and upload wizard behavior.

Files /admin/content/files

View, manage, and perform bulk operations on all files uploaded to the site. Filter by filename, MIME type, status, and file type.

Add file /file/add

Multi-step wizard for uploading files. Steps include file upload, file type selection (if multiple types match), destination scheme selection (if multiple schemes available), and additional field configuration.

Upload archive /admin/content/files/archive

Upload and extract archive files (ZIP, TAR, etc.) to create multiple file entities at once.

View file /file/{file}

View a file entity with its rendered display using the configured view mode for the file type.

Edit file /file/{file}/edit

Edit a file entity's fields and optionally replace the file with a new upload.

File usage /file/{file}/usage

View all entities that reference this file, showing entity label, entity type, registering module, and use count.

Download file /file/{file}/download

Download the file with proper headers and optional HMAC token validation for secure downloads.

権限 14
Bypass file access control

View, edit and delete all files regardless of permission restrictions. Warning: Give to trusted roles only.

Administer file types

Create, edit, enable, disable, and delete file types. Warning: Give to trusted roles only.

Administer files

Full administrative access to all files including settings configuration. Warning: Give to trusted roles only.

Add and upload new files

Allows users to upload new files through the file add form.

View own private files

View private files uploaded by the current user.

View own files

View files uploaded by the current user regardless of stream wrapper.

View private files

View all private files regardless of ownership. Warning: Give to trusted roles only.

View files

View all public files. Granted to all roles on module installation.

Edit own [type] files

Edit files of a specific type that were uploaded by the current user. Generated dynamically for each file type.

Edit any [type] files

Edit any files of a specific type regardless of ownership. Generated dynamically for each file type.

Delete own [type] files

Delete files of a specific type that were uploaded by the current user. Generated dynamically for each file type.

Delete any [type] files

Delete any files of a specific type regardless of ownership. Generated dynamically for each file type.

Download own [type] files

Download files of a specific type that were uploaded by the current user. Generated dynamically for each file type.

Download any [type] files

Download any files of a specific type regardless of ownership. Generated dynamically for each file type.

Hooks 7
hook_file_type

Decides which file type (bundle) should be assigned to a file entity based on custom logic.

hook_file_type_alter

Alters the list of file types that can be assigned to a file, allowing modification of type assignment priority.

hook_file_download_headers_alter

Alters HTTP headers sent when a file is downloaded.

hook_file_transfer

Reacts to a file being downloaded/transferred, useful for redirects or logging.

hook_file_metadata_info

Provides metadata information for file entities.

hook_file_metadata_info_alter

Alters metadata information defined by other modules.

hook_query_file_entity_access_alter

Controls access to listings of files by altering the database query.

Troubleshooting 5
Existing files show 'undefined' type after installation

Run cron to process the file type determination queue. During installation, existing files are queued for classification. Check Reports > Status report to see queue items remaining.

Files not being classified to the expected file type

Check the MIME type patterns configured for each file type at Administration > Structure > File types. Ensure the uploaded file's MIME type matches one of the patterns. Use wildcards (e.g., image/*) for broader matching.

Permission denied when downloading private files

Verify the user has the appropriate 'download any [type] files' or 'download own [type] files' permission. Also check 'view private files' permission for private stream wrapper access.

Image alt/title not displaying

Ensure the Token module is installed and configure the alt/title token patterns at Administration > Configuration > Media > File settings. For images, create the field_image_alt_text and field_image_title_text fields on the image file type.

File replacement not working

File replacement only works for files stored in writable stream wrappers. Check if the file uses a local stream wrapper. Remote or read-only stream wrappers do not support file replacement.

Security Notes 5
  • The 'bypass file access' permission should only be granted to fully trusted administrator roles as it bypasses all file access restrictions.
  • Private files are protected by stream wrapper access checks. Ensure proper permissions are configured for private file viewing and downloading.
  • File downloads include HMAC token validation by default. Do not enable 'allow_insecure_download' unless specifically required.
  • Review file type permissions carefully - type-specific permissions allow granular control over who can edit, delete, and download specific types of files.
  • Be cautious with the archive upload feature - ensure only trusted users have access to prevent potential security issues from extracted files.