function hook_file_download

Same name and namespace in other branches
  1. 7.x modules/system/system.api.php \hook_file_download()
  2. 9 core/lib/Drupal/Core/File/file.api.php \hook_file_download()
  3. 8.9.x core/lib/Drupal/Core/File/file.api.php \hook_file_download()
  4. 10 core/lib/Drupal/Core/File/file.api.php \hook_file_download()

Control access to private file downloads and specify HTTP headers.

This hook allows modules to enforce permissions on file downloads whenever Drupal is handling file download, as opposed to the web server bypassing Drupal and returning the file from a public directory. Modules can also provide headers to specify information like the file's name or MIME type.


$uri: The URI of the file.

Return value

string[]|int If the user does not have permission to access the file, return -1. If the user has permission, return an array with the appropriate headers. If the file is not controlled by the current module, the return value should be NULL.

See also


Related topics

7 functions implement hook_file_download()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

config_file_download in core/modules/config/config.module
Implements hook_file_download().
editor_file_download in core/modules/editor/editor.module
Implements hook_file_download().
file_file_download in core/modules/file/file.module
Implements hook_file_download().
file_test_file_download in core/modules/file/tests/file_test/file_test.module
Implements hook_file_download().
image_file_download in core/modules/image/image.module
Implements hook_file_download().

... See full list

3 invocations of hook_file_download()
FileDownloadController::download in core/modules/system/src/FileDownloadController.php
Handles private file transfers.
ImageStyleDownloadController::deliver in core/modules/image/src/Controller/ImageStyleDownloadController.php
Generates a derivative, given a style and image path.
image_file_download in core/modules/image/image.module
Implements hook_file_download().


core/lib/Drupal/Core/File/file.api.php, line 34


function hook_file_download($uri) {
    // Check to see if this is a config download.
    $scheme = StreamWrapperManager::getScheme($uri);
    $target = StreamWrapperManager::getTarget($uri);
    if ($scheme == 'temporary' && $target == 'config.tar.gz') {
        return [
            'Content-disposition' => 'attachment; filename="config.tar.gz"',

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.