annotate core/lib/Drupal/Core/File/file.api.php @ 19:fa3358dc1485 tip

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