Private Files Download Permission
Provides granular per-directory access control for Drupal's private file system, allowing administrators to restrict file downloads by user and role.
private_files_download_permission
Overview
Private Files Download Permission (PFDP) is a comprehensive access control module for Drupal's private file system. It addresses a common limitation in Drupal's core functionality by providing fine-grained control over who can download files from private directories.
The module allows site administrators to define specific private file system directories and assign download permissions to individual users or roles. Each directory configuration can specify which users and roles are permitted to access files within that directory and its subdirectories. The module uses a best-match algorithm to determine which directory configuration applies to a given file path.
Additional features include the ability to automatically grant file owners access to their uploaded files, bypass mode for directories that should be handled by other modules, and global bypass permissions for administrators. The module also provides performance optimization options such as user list caching and override mode for direct file serving.
Features
- Per-directory access control for private file downloads with path-based matching
- User-based permission assignment allowing specific users to download from defined directories
- Role-based permission assignment for broader access control
- File owner access grants to allow users to download their own uploaded files
- Bypass mode for directories that should be handled by other modules or core
- Global bypass permissions for administrators and temporary files
- Attachment mode to force file downloads instead of inline browser display
- Override mode to skip Drupal's validation chain for faster file serving
- Debug mode with detailed logging of access decisions
- User list caching for improved performance on sites with many users
- Automatic validation of directory paths ensuring proper format with leading slash
- Administrative interface showing current private file system path and configuration status
Use Cases
Restricting Document Downloads to Specific Roles
A company intranet needs to restrict HR documents to HR staff only. Configure a directory entry for '/hr-documents' and enable only the 'HR Staff' role. All other users will be denied access to files in the private://hr-documents directory.
Allowing Users to Access Their Own Uploads
A file sharing site where users upload private documents that only they should access. Create a directory entry for '/' (the entire private file system), enable 'Grant file owners', and do not select any users or roles. This ensures only the file uploader can download their files.
Department-Based File Access
An organization with multiple departments each having their own private file storage. Create separate directory entries for '/finance', '/marketing', '/engineering', etc., and assign the appropriate department role to each entry.
VIP Content Access
Premium content that should be accessible to specific paying members. Create a directory for '/premium-content' and select individual user accounts in the 'Enabled users' section (requires 'Enable by-user checks' in settings).
Mixed Public and Private Handling
Some directories need to be handled by other modules (like media or webform). Set the 'Bypass' option on those directory entries so this module ignores them and lets other modules control access.
High-Traffic Site Optimization
A site with many users experiencing slow file downloads. Enable 'Override mode' in settings to skip Drupal's validation chain and serve files directly. Also enable 'Cache user list' if using per-user checks to improve admin interface performance.
Tips
- Directory paths use best-match logic: a '/documents/confidential' entry takes precedence over '/documents' for files in the confidential subdirectory
- The root path '/' can be used to control the entire private file system
- Use the 'Bypass' option for directories that should be handled by other modules like Media or Webform
- Consider disabling 'by-user checks' on sites with many users if you only need role-based permissions
- The debug log includes user ID, username, and display name for easy identification
- When override mode is enabled, other modules implementing hook_file_download will be bypassed
Technical Details
Admin Pages 5
/admin/config/media/private-files-download-permission
Main administration page displaying a list of all configured private file directories with their access permissions. Shows directory paths, bypass status, enabled users, and enabled roles in a table format. Provides links to edit and delete each directory entry. Also displays informational messages about the current private file system path and whether by-user checks are enabled.
/admin/config/media/private-files-download-permission/add
Form to add a new private file directory entry to the permission control list. Allows specifying the directory path, bypass option, file owner grants, and assigning specific users and roles that can download files from this directory.
/admin/config/media/private-files-download-permission/{pfdp_directory}
Form to edit an existing private file directory entry. Same fields as the add form, but with pre-populated values from the existing configuration.
/admin/config/media/private-files-download-permission/{pfdp_directory}/delete
Confirmation form to delete a directory entry from the permission control list. Removing an entry does not delete any actual files, only the permission configuration.
/admin/config/media/private-files-download-permission/settings
Global settings form for the module, allowing administrators to configure performance options and download behavior.
Permissions 3
Hooks 1
hook_file_download
Controls access to private file downloads. This is the main hook implementation that checks if the current user has permission to download a requested private file based on the configured directory permissions.
Troubleshooting 6
Enable 'Debug mode' in module settings and check the Drupal logs (Reports > Recent log messages) for detailed access decision information including user and URI details.
Configure the private file system path in your settings.php file using: $settings['file_private_path'] = '/path/to/private/files';
Go to Configuration > Media > File system and set the default download method to 'Private local files served by Drupal'.
Enable 'Enable by-user checks' in the module settings (/admin/config/media/private-files-download-permission/settings).
Enable 'Cache user list' in module settings to cache the user list used in the directory edit form.
Disable 'Override mode' in settings to restore the normal Drupal file download validation chain.
Security Notes 5
- This module only affects private file downloads - public files are not controlled
- The 'bypass pfdp' permission should only be granted to highly trusted roles as it allows access to all private files
- Override mode skips other modules' access checks which may have security implications
- Directory paths are case-insensitive when matching
- Files without a matching directory configuration will be denied by default