file_example.module

<?php


/**
 * @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;

/**
 * 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;
}