File Entity (fieldable files)
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
Install
composer require 'drupal/file_entity:8.x-2.3'
composer require 'drupal/file_entity:8.x-2.0'
Overview
File Entity is a comprehensive module that transforms Drupal's core file entity into a fully-featured content entity. It enables files to have custom fields attached via the Field UI, be organized into types (bundles) based on MIME type, and be displayed using various view modes and field formatters.
The module provides built-in file types for images, audio, video, and documents, each automatically classifying uploaded files based on their MIME type. It includes HTML5 audio and video formatters, responsive image support, and download link formatters with token support for dynamic link text.
File Entity integrates deeply with Drupal's ecosystem, providing Views integration for file listing and filtering, Token API support for dynamic alt/title text, optional Pathauto integration for file URL aliases, and REST/HAL API normalizers for headless Drupal implementations.
Features
- Fieldable file entities - attach any Drupal field type to files using Field UI
- File type bundles (Image, Audio, Video, Document) with automatic MIME type classification
- Custom file types with configurable MIME type patterns
- Multi-step file upload wizard with type selection, destination scheme, and field configuration
- HTML5 audio player formatter with controls, autoplay, and loop options
- HTML5 video player formatter with controls, autoplay, loop, muted, and dimension settings
- Responsive image formatter supporting responsive image styles
- Download link formatter with customizable link text supporting tokens
- File size formatter displaying human-readable file sizes
- Inline file editing widget with AJAX modal dialog
- Archive upload and extraction functionality
- File metadata storage (image dimensions, etc.) in dedicated database table
- Granular access control based on file ownership, type, and stream wrapper
- Dynamic permissions per file type (edit/delete/download own/any)
- Views integration with custom fields, filters, and arguments for file management
- Token API integration for dynamic alt and title attributes on images
- Pathauto integration for file URL aliases
- REST and HAL API normalizers for headless Drupal with base64 file content
- Bulk actions for delete, set permanent, and set temporary status
- File usage tracking view showing where each file is used
- Theme suggestions based on file type, MIME type, and view mode
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
/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.
/admin/structure/file-types/add
Create a new file type by defining its label, machine name, description, and associated MIME types.
/admin/structure/file-types/manage/{file_type}/edit
Modify an existing file type's settings including label, description, and MIME type associations.
/admin/config/media/file-settings
Configure global file entity settings including upload limits, allowed extensions, default alt/title attributes, and upload wizard behavior.
/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.
/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.
/admin/content/files/archive
Upload and extract archive files (ZIP, TAR, etc.) to create multiple file entities at once.
/file/{file}
View a file entity with its rendered display using the configured view mode for the file type.
/file/{file}/edit
Edit a file entity's fields and optionally replace the file with a new upload.
/file/{file}/usage
View all entities that reference this file, showing entity label, entity type, registering module, and use count.
/file/{file}/download
Download the file with proper headers and optional HMAC token validation for secure downloads.
Permissions 14
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
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.
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.
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.
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 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.