aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/File/file.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks related to the File management system.
   6  */
   7
   8 /**
   9  * @addtogroup hooks
  10  * @{
  11  */
  12
  13 /**
  14  * Control access to private file downloads and specify HTTP headers.
  15  *
  16  * This hook allows modules to enforce permissions on file downloads whenever
  17  * Drupal is handling file download, as opposed to the web server bypassing
  18  * Drupal and returning the file from a public directory. Modules can also
  19  * provide headers to specify information like the file's name or MIME type.
  20  *
  21  * @param $uri
  22  *   The URI of the file.
  23  * @return
  24  *   If the user does not have permission to access the file, return -1. If the
  25  *   user has permission, return an array with the appropriate headers. If the
  26  *   file is not controlled by the current module, the return value should be
  27  *   NULL.
  28  *
  29  * @see \Drupal\system\FileDownloadController::download()
  30  */
  31 function hook_file_download($uri) {
  32   // Check to see if this is a config download.
  33   $scheme = file_uri_scheme($uri);
  34   $target = file_uri_target($uri);
  35   if ($scheme == 'temporary' && $target == 'config.tar.gz') {
  36     return [
  37       'Content-disposition' => 'attachment; filename="config.tar.gz"',
  38     ];
  39   }
  40 }
  41
  42 /**
  43  * Alter the URL to a file.
  44  *
  45  * This hook is called from file_create_url(), and  is called fairly
  46  * frequently (10+ times per page), depending on how many files there are in a
  47  * given page.
  48  * If CSS and JS aggregation are disabled, this can become very frequently
  49  * (50+ times per page) so performance is critical.
  50  *
  51  * This function should alter the URI, if it wants to rewrite the file URL.
  52  *
  53  * @param $uri
  54  *   The URI to a file for which we need an external URL, or the path to a
  55  *   shipped file.
  56  */
  57 function hook_file_url_alter(&$uri) {
  58   $user = \Drupal::currentUser();
  59
  60   // User 1 will always see the local file in this example.
  61   if ($user->id() == 1) {
  62     return;
  63   }
  64
  65   $cdn1 = 'http://cdn1.example.com';
  66   $cdn2 = 'http://cdn2.example.com';
  67   $cdn_extensions = ['css', 'js', 'gif', 'jpg', 'jpeg', 'png'];
  68
  69   // Most CDNs don't support private file transfers without a lot of hassle,
  70   // so don't support this in the common case.
  71   $schemes = ['public'];
  72
  73   $scheme = file_uri_scheme($uri);
  74
  75   // Only serve shipped files and public created files from the CDN.
  76   if (!$scheme || in_array($scheme, $schemes)) {
  77     // Shipped files.
  78     if (!$scheme) {
  79       $path = $uri;
  80     }
  81     // Public created files.
  82     else {
  83       $wrapper = \Drupal::service('stream_wrapper_manager')->getViaScheme($scheme);
  84       $path = $wrapper->getDirectoryPath() . '/' . file_uri_target($uri);
  85     }
  86
  87     // Clean up Windows paths.
  88     $path = str_replace('\\', '/', $path);
  89
  90     // Serve files with one of the CDN extensions from CDN 1, all others from
  91     // CDN 2.
  92     $pathinfo = pathinfo($path);
  93     if (isset($pathinfo['extension']) && in_array($pathinfo['extension'], $cdn_extensions)) {
  94       $uri = $cdn1 . '/' . $path;
  95     }
  96     else {
  97       $uri = $cdn2 . '/' . $path;
  98     }
  99   }
 100 }
 101
 102 /**
 103  * Alter MIME type mappings used to determine MIME type from a file extension.
 104  *
 105  * Invoked by \Drupal\Core\File\MimeType\ExtensionMimeTypeGuesser::guess(). It
 106  * is used to allow modules to add to or modify the default mapping from
 107  * \Drupal\Core\File\MimeType\ExtensionMimeTypeGuesser::$defaultMapping.
 108  *
 109  * @param $mapping
 110  *   An array of mimetypes correlated to the extensions that relate to them.
 111  *   The array has 'mimetypes' and 'extensions' elements, each of which is an
 112  *   array.
 113  *
 114  * @see \Drupal\Core\File\MimeType\ExtensionMimeTypeGuesser::guess()
 115  * @see \Drupal\Core\File\MimeType\ExtensionMimeTypeGuesser::$defaultMapping
 116  */
 117 function hook_file_mimetype_mapping_alter(&$mapping) {
 118   // Add new MIME type 'drupal/info'.
 119   $mapping['mimetypes']['example_info'] = 'drupal/info';
 120   // Add new extension '.info.yml' and map it to the 'drupal/info' MIME type.
 121   $mapping['extensions']['info'] = 'example_info';
 122   // Override existing extension mapping for '.ogg' files.
 123   $mapping['extensions']['ogg'] = 189;
 124 }
 125
 126 /**
 127  * Alter archiver information declared by other modules.
 128  *
 129  * See hook_archiver_info() for a description of archivers and the archiver
 130  * information structure.
 131  *
 132  * @param $info
 133  *   Archiver information to alter (return values from hook_archiver_info()).
 134  */
 135 function hook_archiver_info_alter(&$info) {
 136   $info['tar']['extensions'][] = 'tgz';
 137 }
 138
 139 /**
 140  * Register information about FileTransfer classes provided by a module.
 141  *
 142  * The FileTransfer class allows transferring files over a specific type of
 143  * connection. Core provides classes for FTP and SSH. Contributed modules are
 144  * free to extend the FileTransfer base class to add other connection types,
 145  * and if these classes are registered via hook_filetransfer_info(), those
 146  * connection types will be available to site administrators using the Update
 147  * manager when they are redirected to the authorize.php script to authorize
 148  * the file operations.
 149  *
 150  * @return array
 151  *   Nested array of information about FileTransfer classes. Each key is a
 152  *   FileTransfer type (not human readable, used for form elements and
 153  *   variable names, etc), and the values are subarrays that define properties
 154  *   of that type. The keys in each subarray are:
 155  *   - 'title': Required. The human-readable name of the connection type.
 156  *   - 'class': Required. The name of the FileTransfer class. The constructor
 157  *     will always be passed the full path to the root of the site that should
 158  *     be used to restrict where file transfer operations can occur (the $jail)
 159  *     and an array of settings values returned by the settings form.
 160  *   - 'weight': Optional. Integer weight used for sorting connection types on
 161  *     the authorize.php form.
 162  *
 163  * @see \Drupal\Core\FileTransfer\FileTransfer
 164  * @see authorize.php
 165  * @see hook_filetransfer_info_alter()
 166  * @see drupal_get_filetransfer_info()
 167  */
 168 function hook_filetransfer_info() {
 169   $info['sftp'] = [
 170     'title' => t('SFTP (Secure FTP)'),
 171     'class' => 'Drupal\Core\FileTransfer\SFTP',
 172     'weight' => 10,
 173   ];
 174   return $info;
 175 }
 176
 177 /**
 178  * Alter the FileTransfer class registry.
 179  *
 180  * @param array $filetransfer_info
 181  *   Reference to a nested array containing information about the FileTransfer
 182  *   class registry.
 183  *
 184  * @see hook_filetransfer_info()
 185  */
 186 function hook_filetransfer_info_alter(&$filetransfer_info) {
 187   // Remove the FTP option entirely.
 188   unset($filetransfer_info['ftp']);
 189   // Make sure the SSH option is listed first.
 190   $filetransfer_info['ssh']['weight'] = -10;
 191 }
 192
 193 /**
 194  * @} End of "addtogroup hooks".
 195  */