file_example.module

<?php


/**
 * @file
 * Hook implementations for the File Example module.
 */


/**
 * @defgroup file_example Example: Files
 * @ingroup examples
 * @{
 * Examples demonstrating the Drupal File API.
 *
 * The File Example module is part of the Examples for Developers Project and
 * provides a variety of examples for the Developers project page.  Some
 * concepts we demonstrate with this module:
 *
 *   * Creating, moving and deleting files, and reading and writing from them.
 *
 *   * Using files that Drupal can manage via its Entity API ("managed files"),
 *     and unmanaged files (the usual kind of file programs deal with).
 *
 *   * Creating and setting up directories with the right permissions, and with
 *     .htaccess files that prevent unwanted accesses.
 *
 *   * Allowing restricted access to files the way Drupal private files are
 *     downloaded.
 *
 *   * Using special "stream" URIs like public://, private://, and temporary://.
 *     Drupal has good support for this PHP language feature.  You can implement
 *     new file schemes as well; see the Stream Wrapper Example for how to do
 *     that.If you enable the stream_wrapper_example module, you can use it
 *     together with the File Example to test how a custom stream works.
 *
 * To demonstrate all of this, the File Example implements a form that lets you
 * play with files. Read src/Form/FileExampleReadWriteForm.php to see
 * demonstrations of the various File API functions you will want to use in your
 * code.
 *
 * See also @link file File interface @endlink for further information on the
 * File API.
 */
use Drupal\Core\StreamWrapper\StreamWrapperManager;
// phpcs:disable Drupal.Commenting.HookComment.HookParamDoc
// phpcs:disable Drupal.Commenting.HookComment.HookReturnDoc

/**
 * Implements hook_file_download().
 *
 * 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.
 *
 * For our example module, we want to be able to see the temporary, private,
 * and session (our test stream wrapper / file scheme).  In general, you really
 * would NEVER give general access to your temporary, and you certainly wouldn't
 * do it for your private files. So we demonstrate this here, but don't try this
 * at home. Remember: keep your files secure!
 *
 * For hook_file_download() to get called at all, your code needs set up your
 * routes so that the download link uses FileDownloadController::download() as
 * a controller. FileDownloadController::download() enforces access restrictions
 * on the files it managed, in part by invoking hook_file_downloads(). Check the
 * routing file used by this module to see how to achieve this.
 *
 * @param string $uri
 *   The file URI.
 *
 * @return mixed
 *   If the current user does not have the permission to access the file,
 *   return -1; otherwise, return an array with the appropriate headers.
 *   If the file is not controlled by a module, that module should return NULL.
 *
 * @see \Drupal\system\FileDownloadController::download()
 */
function file_example_file_download($uri) {
  $scheme = StreamWrapperManager::getScheme($uri);
  if (in_array($scheme, [
    'private',
    'temporary',
    'session',
  ])) {
    $permission = "read {$scheme} files";
    $current_user = \Drupal::currentUser();
    $account = $current_user->getAccount();
    if ($account->hasPermission($permission)) {
      // If the current user has the permission to access the file, return an
      // array with the appropriate headers.
      return [
        'Content-Type: text/plain',
      ];
    }
  }
  // If the current user does not have the permission to access the file, return
  // -1. This is what FileDownloadController::download() expect to obtain in
  // that case.
  return -1;
}