file.module 72.6 KB
Newer Older
1 2 3 4 5 6 7
<?php

/**
 * @file
 * Defines a "managed_file" Form API field and a "file" field for Field module.
 */

8
use Drupal\Component\Utility\Environment;
9
use Drupal\Core\Datetime\Entity\DateFormat;
10
use Drupal\Core\Field\FieldDefinitionInterface;
11 12
use Drupal\Core\File\Exception\FileException;
use Drupal\Core\File\FileSystemInterface;
13
use Drupal\Core\Form\FormStateInterface;
14
use Drupal\Core\Messenger\MessengerInterface;
15
use Drupal\Core\Render\BubbleableMetadata;
16
use Drupal\Core\Render\Element;
17
use Drupal\Core\Routing\RouteMatchInterface;
18
use Drupal\Core\Link;
19
use Drupal\Core\Url;
20
use Drupal\file\Entity\File;
21
use Drupal\file\FileInterface;
22
use Drupal\Component\Utility\NestedArray;
23
use Drupal\Component\Utility\Unicode;
24
use Drupal\Core\Entity\EntityStorageInterface;
25
use Drupal\Core\Template\Attribute;
26
use Symfony\Component\Mime\MimeTypeGuesserInterface;
27

28 29 30
/**
 * The regex pattern used when checking for insecure file types.
 */
31
define('FILE_INSECURE_EXTENSION_REGEX', '/\.(phar|php|pl|py|cgi|asp|js)(\.|$)/i');
32

33
// Load all Field module hooks for File.
34
require_once __DIR__ . '/file.field.inc';
35

36 37 38
/**
 * Implements hook_help().
 */
39
function file_help($route_name, RouteMatchInterface $route_match) {
40 41
  switch ($route_name) {
    case 'help.page.file':
42 43
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
44
      $output .= '<p>' . t('The File module allows you to create fields that contain files. See the <a href=":field">Field module help</a> and the <a href=":field_ui">Field UI help</a> pages for general information on fields and how to create and manage them. For more information, see the <a href=":file_documentation">online documentation for the File module</a>.', [':field' => Url::fromRoute('help.page', ['name' => 'field'])->toString(), ':field_ui' => (\Drupal::moduleHandler()->moduleExists('field_ui')) ? Url::fromRoute('help.page', ['name' => 'field_ui'])->toString() : '#', ':file_documentation' => 'https://www.drupal.org/documentation/modules/file']) . '</p>';
45 46
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
47
      $output .= '<dt>' . t('Managing and displaying file fields') . '</dt>';
48
      $output .= '<dd>' . t('The <em>settings</em> and the <em>display</em> of the file field can be configured separately. See the <a href=":field_ui">Field UI help</a> for more information on how to manage fields and their display.', [':field_ui' => (\Drupal::moduleHandler()->moduleExists('field_ui')) ? Url::fromRoute('help.page', ['name' => 'field_ui'])->toString() : '#']) . '</dd>';
49 50
      $output .= '<dt>' . t('Allowing file extensions') . '</dt>';
      $output .= '<dd>' . t('In the field settings, you can define the allowed file extensions (for example <em>pdf docx psd</em>) for the files that will be uploaded with the file field.') . '</dd>';
51
      $output .= '<dt>' . t('Storing files') . '</dt>';
52
      $output .= '<dd>' . t('Uploaded files can either be stored as <em>public</em> or <em>private</em>, depending on the <a href=":file-system">File system settings</a>. For more information, see the <a href=":system-help">System module help page</a>.', [':file-system' => Url::fromRoute('system.file_system_settings')->toString(), ':system-help' => Url::fromRoute('help.page', ['name' => 'system'])->toString()]) . '</dd>';
53 54 55 56
      $output .= '<dt>' . t('Restricting the maximum file size') . '</dt>';
      $output .= '<dd>' . t('The maximum file size that users can upload is limited by PHP settings of the server, but you can restrict by entering the desired value as the <em>Maximum upload size</em> setting. The maximum file size is automatically displayed to users in the help text of the file field.') . '</dd>';
      $output .= '<dt>' . t('Displaying files and descriptions') . '<dt>';
      $output .= '<dd>' . t('In the field settings, you can allow users to toggle whether individual files are displayed. In the display settings, you can then choose one of the following formats: <ul><li><em>Generic file</em> displays links to the files and adds icons that symbolize the file extensions. If <em>descriptions</em> are enabled and have been submitted, then the description is displayed instead of the file name.</li><li><em>URL to file</em> displays the full path to the file as plain text.</li><li><em>Table of files</em> lists links to the files and the file sizes in a table.</li><li><em>RSS enclosure</em> only displays the first file, and only in a RSS feed, formatted according to the RSS 2.0 syntax for enclosures.</li></ul> A file can still be linked to directly by its URI even if it is not displayed.') . '</dd>';
57 58 59 60 61
      $output .= '</dl>';
      return $output;
  }
}

62 63 64 65 66 67 68 69 70 71
/**
 * Implements hook_field_widget_info_alter().
 */
function file_field_widget_info_alter(array &$info) {
  // Allows using the 'uri' widget for the 'file_uri' field type, which uses it
  // as the default widget.
  // @see \Drupal\file\Plugin\Field\FieldType\FileUriItem
  $info['uri']['field_types'][] = 'file_uri';
}

72 73 74 75 76 77 78 79 80
/**
 * Copies a file to a new location and adds a file record to the database.
 *
 * This function should be used when manipulating files that have records
 * stored in the database. This is a powerful function that in many ways
 * performs like an advanced version of copy().
 * - Checks if $source and $destination are valid and readable/writable.
 * - If file already exists in $destination either the call will error out,
 *   replace the file or rename the file based on the $replace parameter.
81
 * - If the $source and $destination are equal, the behavior depends on the
82 83 84
 *   $replace parameter. FileSystemInterface::EXISTS_REPLACE will error out.
 *   FileSystemInterface::EXISTS_RENAME will rename the file until the
 *   $destination is unique.
85 86 87 88
 * - Adds the new file to the files database. If the source file is a
 *   temporary file, the resulting file will also be a temporary file. See
 *   file_save_upload() for details on temporary files.
 *
89
 * @param \Drupal\file\FileInterface $source
90
 *   A file entity.
91
 * @param string $destination
92 93
 *   A string containing the destination that $source should be
 *   copied to. This must be a stream wrapper URI.
94
 * @param int $replace
95 96
 *   (optional) Replace behavior when the destination file already exists.
 *   Possible values include:
97 98 99 100 101 102 103
 *   - FileSystemInterface::EXISTS_REPLACE: Replace the existing file. If a
 *     managed file with the destination name exists, then its database entry
 *     will be updated. If no database entry is found, then a new one will be
 *     created.
 *   - FileSystemInterface::EXISTS_RENAME: (default) Append
 *     _{incrementing number} until the filename is unique.
 *   - FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.
104
 *
105 106
 * @return \Drupal\file\FileInterface|false
 *   File entity if the copy is successful, or FALSE in the event of an error.
107
 *
108
 * @see \Drupal\Core\File\FileSystemInterface::copy()
109 110
 * @see hook_file_copy()
 */
111
function file_copy(FileInterface $source, $destination = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
112 113
  /** @var \Drupal\Core\File\FileSystemInterface $file_system */
  $file_system = \Drupal::service('file_system');
114 115 116 117
  /** @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager */
  $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');

  if (!$stream_wrapper_manager->isValidUri($destination)) {
118
    if (($realpath = $file_system->realpath($source->getFileUri())) !== FALSE) {
119
      \Drupal::logger('file')->notice('File %file (%realpath) could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', ['%file' => $source->getFileUri(), '%realpath' => $realpath, '%destination' => $destination]);
120 121
    }
    else {
122
      \Drupal::logger('file')->notice('File %file could not be copied because the destination %destination is invalid. This is often caused by improper use of file_copy() or a missing stream wrapper.', ['%file' => $source->getFileUri(), '%destination' => $destination]);
123
    }
124
    \Drupal::messenger()->addError(t('The specified file %file could not be copied because the destination is invalid. More information is available in the system log.', ['%file' => $source->getFileUri()]));
125 126 127
    return FALSE;
  }

128 129
  try {
    $uri = $file_system->copy($source->getFileUri(), $destination, $replace);
130 131
    $file = $source->createDuplicate();
    $file->setFileUri($uri);
132
    $file->setFilename($file_system->basename($uri));
133
    // If we are replacing an existing file re-use its database record.
134 135
    // @todo Do not create a new entity in order to update it. See
    //   https://www.drupal.org/node/2241865.
136
    if ($replace == FileSystemInterface::EXISTS_REPLACE) {
137
      $existing_files = \Drupal::entityTypeManager()->getStorage('file')->loadByProperties(['uri' => $uri]);
138 139
      if (count($existing_files)) {
        $existing = reset($existing_files);
140
        $file->fid = $existing->id();
141
        $file->setOriginalId($existing->id());
142
        $file->setFilename($existing->getFilename());
143 144 145 146
      }
    }
    // If we are renaming around an existing file (rather than a directory),
    // use its basename for the filename.
147
    elseif ($replace == FileSystemInterface::EXISTS_RENAME && is_file($destination)) {
148
      $file->setFilename($file_system->basename($destination));
149 150 151 152 153
    }

    $file->save();

    // Inform modules that the file has been copied.
154
    \Drupal::moduleHandler()->invokeAll('file_copy', [$file, $source]);
155 156 157

    return $file;
  }
158 159 160
  catch (FileException $e) {
    return FALSE;
  }
161 162 163 164 165 166 167 168 169 170 171
}

/**
 * Moves a file to a new location and update the file's database entry.
 *
 * - Checks if $source and $destination are valid and readable/writable.
 * - Performs a file move if $source is not equal to $destination.
 * - If file already exists in $destination either the call will error out,
 *   replace the file or rename the file based on the $replace parameter.
 * - Adds the new file to the files database.
 *
172
 * @param \Drupal\file\FileInterface $source
173
 *   A file entity.
174
 * @param string $destination
175 176
 *   A string containing the destination that $source should be moved
 *   to. This must be a stream wrapper URI.
177
 * @param int $replace
178 179
 *   (optional) The replace behavior when the destination file already exists.
 *   Possible values include:
180 181 182 183 184 185 186 187
 *   - FileSystemInterface::EXISTS_REPLACE: Replace the existing file. If a
 *     managed file with the destination name exists then its database entry
 *     will be updated and $source->delete() called after invoking
 *     hook_file_move(). If no database entry is found, then the source files
 *     record will be updated.
 *   - FileSystemInterface::EXISTS_RENAME: (default) Append
 *     _{incrementing number} until the filename is unique.
 *   - FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.
188
 *
189
 * @return \Drupal\file\FileInterface|false
190 191
 *   Resulting file entity for success, or FALSE in the event of an error.
 *
192
 * @see \Drupal\Core\File\FileSystemInterface::move()
193 194
 * @see hook_file_move()
 */
195
function file_move(FileInterface $source, $destination = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
196 197
  /** @var \Drupal\Core\File\FileSystemInterface $file_system */
  $file_system = \Drupal::service('file_system');
198 199 200 201
  /** @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager */
  $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');

  if (!$stream_wrapper_manager->isValidUri($destination)) {
202
    if (($realpath = $file_system->realpath($source->getFileUri())) !== FALSE) {
203
      \Drupal::logger('file')->notice('File %file (%realpath) could not be moved because the destination %destination is invalid. This may be caused by improper use of file_move() or a missing stream wrapper.', ['%file' => $source->getFileUri(), '%realpath' => $realpath, '%destination' => $destination]);
204 205
    }
    else {
206
      \Drupal::logger('file')->notice('File %file could not be moved because the destination %destination is invalid. This may be caused by improper use of file_move() or a missing stream wrapper.', ['%file' => $source->getFileUri(), '%destination' => $destination]);
207
    }
208
    \Drupal::messenger()->addError(t('The specified file %file could not be moved because the destination is invalid. More information is available in the system log.', ['%file' => $source->getFileUri()]));
209 210 211
    return FALSE;
  }

212 213
  try {
    $uri = $file_system->move($source->getFileUri(), $destination, $replace);
214 215 216
    $delete_source = FALSE;

    $file = clone $source;
217
    $file->setFileUri($uri);
218
    // If we are replacing an existing file re-use its database record.
219
    if ($replace == FileSystemInterface::EXISTS_REPLACE) {
220
      $existing_files = \Drupal::entityTypeManager()->getStorage('file')->loadByProperties(['uri' => $uri]);
221 222 223
      if (count($existing_files)) {
        $existing = reset($existing_files);
        $delete_source = TRUE;
224
        $file->fid = $existing->id();
225
        $file->uuid = $existing->uuid();
226 227 228 229
      }
    }
    // If we are renaming around an existing file (rather than a directory),
    // use its basename for the filename.
230
    elseif ($replace == FileSystemInterface::EXISTS_RENAME && is_file($destination)) {
231
      $file->setFilename(\Drupal::service('file_system')->basename($destination));
232 233 234 235 236
    }

    $file->save();

    // Inform modules that the file has been moved.
237
    \Drupal::moduleHandler()->invokeAll('file_move', [$file, $source]);
238 239

    // Delete the original if it's not in use elsewhere.
240
    if ($delete_source && !\Drupal::service('file.usage')->listUsage($source)) {
241 242 243 244 245
      $source->delete();
    }

    return $file;
  }
246 247 248
  catch (FileException $e) {
    return FALSE;
  }
249 250 251 252 253 254 255 256
}

/**
 * Checks that a file meets the criteria specified by the validators.
 *
 * After executing the validator callbacks specified hook_file_validate() will
 * also be called to allow other modules to report errors about the file.
 *
257
 * @param \Drupal\file\FileInterface $file
258
 *   A file entity.
259
 * @param array $validators
260 261 262 263 264 265 266
 *   (optional) An associative array of callback functions used to validate
 *   the file. The keys are function names and the values arrays of callback
 *   parameters which will be passed in after the file entity. The functions
 *   should return an array of error messages; an empty array indicates that
 *   the file passed validation. The callback functions will be called in the
 *   order specified in the array, then the hook hook_file_validate()
 *   will be invoked so other modules can validate the new file.
267
 *
268
 * @return array
269 270 271 272
 *   An array containing validation error messages.
 *
 * @see hook_file_validate()
 */
273
function file_validate(FileInterface $file, $validators = []) {
274
  // Call the validation functions specified by this function's caller.
275
  $errors = [];
276 277 278 279 280 281 282 283
  foreach ($validators as $function => $args) {
    if (function_exists($function)) {
      array_unshift($args, $file);
      $errors = array_merge($errors, call_user_func_array($function, $args));
    }
  }

  // Let other modules perform validation on the new file.
284 285 286 287 288 289 290 291 292 293 294
  $errors = array_merge($errors, \Drupal::moduleHandler()->invokeAll('file_validate', [$file]));

  // Ensure the file does not contain a malicious extension. At this point
  // _file_save_upload_single() will have munged the file so it does not contain
  // a malicious extension. Contributed and custom code that calls this method
  // needs to take similar steps if they need to permit files with malicious
  // extensions to be uploaded.
  if (empty($errors) && !\Drupal::config('system.file')->get('allow_insecure_uploads') && preg_match(FILE_INSECURE_EXTENSION_REGEX, $file->getFilename())) {
    $errors[] = t('For security reasons, your upload has been rejected.');
  }
  return $errors;
295 296 297 298 299
}

/**
 * Checks for files with names longer than can be stored in the database.
 *
300
 * @param \Drupal\file\FileInterface $file
301 302
 *   A file entity.
 *
303
 * @return array
304 305
 *   An empty array if the file name length is smaller than the limit or an
 *   array containing an error message if it's not or is empty.
306
 */
307
function file_validate_name_length(FileInterface $file) {
308
  $errors = [];
309

310
  if (!$file->getFilename()) {
311 312
    $errors[] = t("The file's name is empty. Please give a name to the file.");
  }
313
  if (strlen($file->getFilename()) > 240) {
314 315 316 317 318 319 320 321
    $errors[] = t("The file's name exceeds the 240 characters limit. Please rename the file and try again.");
  }
  return $errors;
}

/**
 * Checks that the filename ends with an allowed extension.
 *
322
 * @param \Drupal\file\FileInterface $file
323
 *   A file entity.
324
 * @param string $extensions
325 326
 *   A string with a space separated list of allowed extensions.
 *
327
 * @return array
328 329
 *   An empty array if the file extension is allowed or an array containing an
 *   error message if it's not.
330 331 332
 *
 * @see hook_file_validate()
 */
333
function file_validate_extensions(FileInterface $file, $extensions) {
334
  $errors = [];
335 336

  $regex = '/\.(' . preg_replace('/ +/', '|', preg_quote($extensions)) . ')$/i';
337
  if (!preg_match($regex, $file->getFilename())) {
338
    $errors[] = t('Only files with the following extensions are allowed: %files-allowed.', ['%files-allowed' => $extensions]);
339 340 341 342 343 344 345
  }
  return $errors;
}

/**
 * Checks that the file's size is below certain limits.
 *
346
 * @param \Drupal\file\FileInterface $file
347
 *   A file entity.
348
 * @param int $file_limit
349 350
 *   (optional) The maximum file size in bytes. Zero (the default) indicates
 *   that no limit should be enforced.
351
 * @param int $user_limit
352 353
 *   (optional) The maximum number of bytes the user is allowed. Zero (the
 *   default) indicates that no limit should be enforced.
354
 *
355
 * @return array
356 357
 *   An empty array if the file size is below limits or an array containing an
 *   error message if it's not.
358 359 360
 *
 * @see hook_file_validate()
 */
361
function file_validate_size(FileInterface $file, $file_limit = 0, $user_limit = 0) {
362
  $user = \Drupal::currentUser();
363
  $errors = [];
364

365
  if ($file_limit && $file->getSize() > $file_limit) {
366
    $errors[] = t('The file is %filesize exceeding the maximum file size of %maxsize.', ['%filesize' => format_size($file->getSize()), '%maxsize' => format_size($file_limit)]);
367
  }
368

369
  // Save a query by only calling spaceUsed() when a limit is provided.
370
  if ($user_limit && (\Drupal::entityTypeManager()->getStorage('file')->spaceUsed($user->id()) + $file->getSize()) > $user_limit) {
371
    $errors[] = t('The file is %filesize which would exceed your disk quota of %quota.', ['%filesize' => format_size($file->getSize()), '%quota' => format_size($user_limit)]);
372
  }
373

374 375 376 377
  return $errors;
}

/**
378
 * Checks that the file is recognized as a valid image.
379
 *
380
 * @param \Drupal\file\FileInterface $file
381 382
 *   A file entity.
 *
383
 * @return array
384 385
 *   An empty array if the file is a valid image or an array containing an error
 *   message if it's not.
386 387 388
 *
 * @see hook_file_validate()
 */
389
function file_validate_is_image(FileInterface $file) {
390
  $errors = [];
391

392 393 394 395
  $image_factory = \Drupal::service('image.factory');
  $image = $image_factory->get($file->getFileUri());
  if (!$image->isValid()) {
    $supported_extensions = $image_factory->getSupportedExtensions();
396
    $errors[] = t('The image file is invalid or the image type is not allowed. Allowed types: %types', ['%types' => implode(', ', $supported_extensions)]);
397 398 399 400 401 402 403 404
  }

  return $errors;
}

/**
 * Verifies that image dimensions are within the specified maximum and minimum.
 *
405
 * Non-image files will be ignored. If an image toolkit is available the image
406 407
 * will be scaled to fit within the desired maximum dimensions.
 *
408
 * @param \Drupal\file\FileInterface $file
409
 *   A file entity. This function may resize the file affecting its size.
410 411 412 413 414 415 416 417 418
 * @param string|int $maximum_dimensions
 *   (optional) A string in the form WIDTHxHEIGHT; for example, '640x480' or
 *   '85x85'. If an image toolkit is installed, the image will be resized down
 *   to these dimensions. A value of zero (the default) indicates no restriction
 *   on size, so no resizing will be attempted.
 * @param string|int $minimum_dimensions
 *   (optional) A string in the form WIDTHxHEIGHT. This will check that the
 *   image meets a minimum size. A value of zero (the default) indicates that
 *   there is no restriction on size.
419
 *
420 421 422 423 424
 * @return array
 *   An empty array if the file meets the specified dimensions, was resized
 *   successfully to meet those requirements or is not an image. If the image
 *   does not meet the requirements or an attempt to resize it fails, an array
 *   containing the error message will be returned.
425 426 427
 *
 * @see hook_file_validate()
 */
428
function file_validate_image_resolution(FileInterface $file, $maximum_dimensions = 0, $minimum_dimensions = 0) {
429
  $errors = [];
430 431

  // Check first that the file is an image.
432
  $image_factory = \Drupal::service('image.factory');
433
  $image = $image_factory->get($file->getFileUri());
434

435
  if ($image->isValid()) {
436
    $scaling = FALSE;
437 438 439
    if ($maximum_dimensions) {
      // Check that it is smaller than the given dimensions.
      list($width, $height) = explode('x', $maximum_dimensions);
440
      if ($image->getWidth() > $width || $image->getHeight() > $height) {
441
        // Try to resize the image to fit the dimensions.
442
        if ($image->scale($width, $height)) {
443
          $scaling = TRUE;
444
          $image->save();
445
          if (!empty($width) && !empty($height)) {
446 447 448 449 450 451
            $message = t('The image was resized to fit within the maximum allowed dimensions of %dimensions pixels. The new dimensions of the resized image are %new_widthx%new_height pixels.',
              [
                '%dimensions' => $maximum_dimensions,
                '%new_width' => $image->getWidth(),
                '%new_height' => $image->getHeight(),
              ]);
452 453
          }
          elseif (empty($width)) {
454 455 456 457 458 459
            $message = t('The image was resized to fit within the maximum allowed height of %height pixels. The new dimensions of the resized image are %new_widthx%new_height pixels.',
              [
                '%height' => $height,
                '%new_width' => $image->getWidth(),
                '%new_height' => $image->getHeight(),
              ]);
460 461
          }
          elseif (empty($height)) {
462 463 464 465 466 467
            $message = t('The image was resized to fit within the maximum allowed width of %width pixels. The new dimensions of the resized image are %new_widthx%new_height pixels.',
              [
                '%width' => $width,
                '%new_width' => $image->getWidth(),
                '%new_height' => $image->getHeight(),
              ]);
468
          }
469
          \Drupal::messenger()->addStatus($message);
470 471
        }
        else {
472
          $errors[] = t('The image exceeds the maximum allowed dimensions and an attempt to resize it failed.');
473 474 475 476 477 478 479
        }
      }
    }

    if ($minimum_dimensions) {
      // Check that it is larger than the given dimensions.
      list($width, $height) = explode('x', $minimum_dimensions);
480
      if ($image->getWidth() < $width || $image->getHeight() < $height) {
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496
        if ($scaling) {
          $errors[] = t('The resized image is too small. The minimum dimensions are %dimensions pixels and after resizing, the image size will be %widthx%height pixels.',
            [
              '%dimensions' => $minimum_dimensions,
              '%width' => $image->getWidth(),
              '%height' => $image->getHeight(),
            ]);
        }
        else {
          $errors[] = t('The image is too small. The minimum dimensions are %dimensions pixels and the image size is %widthx%height pixels.',
            [
              '%dimensions' => $minimum_dimensions,
              '%width' => $image->getWidth(),
              '%height' => $image->getHeight(),
            ]);
        }
497 498 499 500 501 502 503 504 505 506
      }
    }
  }

  return $errors;
}

/**
 * Saves a file to the specified destination and creates a database entry.
 *
507
 * @param string $data
508
 *   A string containing the contents of the file.
509 510 511 512 513
 * @param string|null $destination
 *   (optional) A string containing the destination URI. This must be a stream
 *   wrapper URI. If no value or NULL is provided, a randomized name will be
 *   generated and the file will be saved using Drupal's default files scheme,
 *   usually "public://".
514
 * @param int $replace
515 516
 *   (optional) The replace behavior when the destination file already exists.
 *   Possible values include:
517 518 519 520 521 522 523
 *   - FileSystemInterface::EXISTS_REPLACE: Replace the existing file. If a
 *     managed file with the destination name exists, then its database entry
 *     will be updated. If no database entry is found, then a new one will be
 *     created.
 *   - FileSystemInterface::EXISTS_RENAME: (default) Append
 *     _{incrementing number} until the filename is unique.
 *   - FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.
524
 *
525
 * @return \Drupal\file\FileInterface|false
526 527
 *   A file entity, or FALSE on error.
 *
528
 * @see \Drupal\Core\File\FileSystemInterface::saveData()
529
 */
530
function file_save_data($data, $destination = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
531
  $user = \Drupal::currentUser();
532 533

  if (empty($destination)) {
534
    $destination = \Drupal::config('system.file')->get('default_scheme') . '://';
535
  }
536 537 538 539

  /** @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager */
  $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');
  if (!$stream_wrapper_manager->isValidUri($destination)) {
540
    \Drupal::logger('file')->notice('The data could not be saved because the destination %destination is invalid. This may be caused by improper use of file_save_data() or a missing stream wrapper.', ['%destination' => $destination]);
541
    \Drupal::messenger()->addError(t('The data could not be saved because the destination is invalid. More information is available in the system log.'));
542 543 544
    return FALSE;
  }

545 546
  try {
    $uri = \Drupal::service('file_system')->saveData($data, $destination, $replace);
547
    // Create a file entity.
548
    $file = File::create([
549
      'uri' => $uri,
550
      'uid' => $user->id(),
551
      'status' => FILE_STATUS_PERMANENT,
552
    ]);
553
    // If we are replacing an existing file re-use its database record.
554 555
    // @todo Do not create a new entity in order to update it. See
    //   https://www.drupal.org/node/2241865.
556
    if ($replace == FileSystemInterface::EXISTS_REPLACE) {
557
      $existing_files = \Drupal::entityTypeManager()->getStorage('file')->loadByProperties(['uri' => $uri]);
558 559
      if (count($existing_files)) {
        $existing = reset($existing_files);
560
        $file->fid = $existing->id();
561
        $file->setOriginalId($existing->id());
562
        $file->setFilename($existing->getFilename());
563 564 565 566
      }
    }
    // If we are renaming around an existing file (rather than a directory),
    // use its basename for the filename.
567
    elseif ($replace == FileSystemInterface::EXISTS_RENAME && is_file($destination)) {
568
      $file->setFilename(\Drupal::service('file_system')->basename($destination));
569 570 571 572 573
    }

    $file->save();
    return $file;
  }
574 575 576 577
  catch (FileException $e) {
    return FALSE;
  }

578 579 580 581 582
}

/**
 * Examines a file entity and returns appropriate content headers for download.
 *
583
 * @param \Drupal\file\FileInterface $file
584 585
 *   A file entity.
 *
586
 * @return array
587 588 589
 *   An associative array of headers, as expected by
 *   \Symfony\Component\HttpFoundation\StreamedResponse.
 */
590
function file_get_content_headers(FileInterface $file) {
591
  $type = Unicode::mimeHeaderEncode($file->getMimeType());
592

593
  return [
594
    'Content-Type' => $type,
595
    'Content-Length' => $file->getSize(),
596
    'Cache-Control' => 'private',
597
  ];
598 599
}

600
/**
601
 * Implements hook_theme().
602 603
 */
function file_theme() {
604
  return [
605
    // From file.module.
606 607 608 609
    'file_link' => [
      'variables' => ['file' => NULL, 'description' => NULL, 'attributes' => []],
    ],
    'file_managed_file' => [
610
      'render element' => 'element',
611
    ],
612 613 614 615 616 617
    'file_audio' => [
      'variables' => ['files' => [], 'attributes' => NULL],
    ],
    'file_video' => [
      'variables' => ['files' => [], 'attributes' => NULL],
    ],
618

619
    // From file.field.inc.
620
    'file_widget_multiple' => [
621
      'render element' => 'element',
622
      'file' => 'file.field.inc',
623 624 625
    ],
    'file_upload_help' => [
      'variables' => ['description' => NULL, 'upload_validators' => NULL, 'cardinality' => NULL],
626
      'file' => 'file.field.inc',
627 628
    ],
  ];
629 630 631
}

/**
632
 * Implements hook_file_download().
633
 */
634
function file_file_download($uri) {
635
  // Get the file record based on the URI. If not in the database just return.
636
  /** @var \Drupal\file\FileInterface[] $files */
637
  $files = \Drupal::entityTypeManager()->getStorage('file')->loadByProperties(['uri' => $uri]);
638
  if (count($files)) {
639 640 641
    foreach ($files as $item) {
      // Since some database servers sometimes use a case-insensitive comparison
      // by default, double check that the filename is an exact match.
642
      if ($item->getFileUri() === $uri) {
643 644 645 646
        $file = $item;
        break;
      }
    }
647
  }
648
  if (!isset($file)) {
649 650 651
    return;
  }

652 653 654 655 656 657 658 659 660 661 662 663 664 665
  // Find out if a temporary file is still used in the system.
  if ($file->isTemporary()) {
    $usage = \Drupal::service('file.usage')->listUsage($file);
    if (empty($usage) && $file->getOwnerId() != \Drupal::currentUser()->id()) {
      // Deny access to temporary files without usage that are not owned by the
      // same user. This prevents the security issue that a private file that
      // was protected by field permissions becomes available after its usage
      // was removed and before it is actually deleted from the file system.
      // Modules that depend on this behavior should make the file permanent
      // instead.
      return -1;
    }
  }

666
  // Find out which (if any) fields of this type contain the file.
667
  $references = file_get_file_references($file, NULL, EntityStorageInterface::FIELD_LOAD_CURRENT, NULL);
668

669 670 671 672 673
  // Stop processing if there are no references in order to avoid returning
  // headers for files controlled by other modules. Make an exception for
  // temporary files where the host entity has not yet been saved (for example,
  // an image preview on a node/add form) in which case, allow download by the
  // file's owner.
674
  if (empty($references) && ($file->isPermanent() || $file->getOwnerId() != \Drupal::currentUser()->id())) {
675
    return;
676 677
  }

678
  if (!$file->access('download')) {
679 680 681 682
    return -1;
  }

  // Access is granted.
683 684
  $headers = file_get_content_headers($file);
  return $headers;
685 686
}

687
/**
688
 * Implements hook_cron().
689 690
 */
function file_cron() {
691
  $age = \Drupal::config('system.file')->get('temporary_maximum_age');
692
  $file_storage = \Drupal::entityTypeManager()->getStorage('file');
693

694 695 696
  /** @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager */
  $stream_wrapper_manager = \Drupal::service('stream_wrapper_manager');

697 698 699 700 701 702 703 704
  // Only delete temporary files if older than $age. Note that automatic cleanup
  // is disabled if $age set to 0.
  if ($age) {
    $fids = Drupal::entityQuery('file')
      ->condition('status', FILE_STATUS_PERMANENT, '<>')
      ->condition('changed', REQUEST_TIME - $age, '<')
      ->range(0, 100)
      ->execute();
705
    $files = $file_storage->loadMultiple($fids);
706
    foreach ($files as $file) {
707
      $references = \Drupal::service('file.usage')->listUsage($file);
708
      if (empty($references)) {
709
        if (!file_exists($file->getFileUri())) {
710
          if (!$stream_wrapper_manager->isValidUri($file->getFileUri())) {
711 712 713 714 715
            \Drupal::logger('file system')->warning('Temporary file "%path" that was deleted during garbage collection did not exist on the filesystem. This could be caused by a missing stream wrapper.', ['%path' => $file->getFileUri()]);
          }
          else {
            \Drupal::logger('file system')->warning('Temporary file "%path" that was deleted during garbage collection did not exist on the filesystem.', ['%path' => $file->getFileUri()]);
          }
716
        }
717 718 719
        // Delete the file entity. If the file does not exist, this will
        // generate a second notice in the watchdog.
        $file->delete();
720 721
      }
      else {
722
        \Drupal::logger('file system')->info('Did not delete temporary file "%path" during garbage collection because it is in use by the following modules: %modules.', ['%path' => $file->getFileUri(), '%modules' => implode(', ', array_keys($references))]);
723 724 725 726 727
      }
    }
  }
}

728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744
/**
 * Saves form file uploads.
 *
 * The files will be added to the {file_managed} table as temporary files.
 * Temporary files are periodically cleaned. Use the 'file.usage' service to
 * register the usage of the file which will automatically mark it as permanent.
 *
 * @param array $element
 *   The FAPI element whose values are being saved.
 * @param \Drupal\Core\Form\FormStateInterface $form_state
 *   The current state of the form.
 * @param null|int $delta
 *   (optional) The delta of the file to return the file entity.
 *   Defaults to NULL.
 * @param int $replace
 *   (optional) The replace behavior when the destination file already exists.
 *   Possible values include:
745 746 747 748
 *   - FileSystemInterface::EXISTS_REPLACE: Replace the existing file.
 *   - FileSystemInterface::EXISTS_RENAME: (default) Append
 *     _{incrementing number} until the filename is unique.
 *   - FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.
749 750 751 752 753 754 755
 *
 * @return array|\Drupal\file\FileInterface|null|false
 *   An array of file entities or a single file entity if $delta != NULL. Each
 *   array element contains the file entity if the upload succeeded or FALSE if
 *   there was an error. Function returns NULL if no file was uploaded.
 *
 * @internal
756 757 758 759
 *   This function is internal, and may be removed in a minor version release.
 *   It wraps file_save_upload() to allow correct error handling in forms.
 *   Contrib and custom code should not call this function, they should use the
 *   managed file upload widgets in core.
760
 *
761 762
 * @see https://www.drupal.org/project/drupal/issues/3069020
 * @see https://www.drupal.org/project/drupal/issues/2482783
763
 */
764
function _file_save_upload_from_form(array $element, FormStateInterface $form_state, $delta = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
765 766
  // Get all errors set before calling this method. This will also clear them
  // from $_SESSION.
767
  $errors_before = \Drupal::messenger()->deleteByType(MessengerInterface::TYPE_ERROR);
768 769 770 771 772 773 774 775 776

  $upload_location = isset($element['#upload_location']) ? $element['#upload_location'] : FALSE;
  $upload_name = implode('_', $element['#parents']);
  $upload_validators = isset($element['#upload_validators']) ? $element['#upload_validators'] : [];

  $result = file_save_upload($upload_name, $upload_validators, $upload_location, $delta, $replace);

  // Get new errors that are generated while trying to save the upload. This
  // will also clear them from $_SESSION.
777 778
  $errors_new = \Drupal::messenger()->deleteByType(MessengerInterface::TYPE_ERROR);
  if (!empty($errors_new)) {
779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802

    if (count($errors_new) > 1) {
      // Render multiple errors into a single message.
      // This is needed because only one error per element is supported.
      $render_array = [
        'error' => [
          '#markup' => t('One or more files could not be uploaded.'),
        ],
        'item_list' => [
          '#theme' => 'item_list',
          '#items' => $errors_new,
        ],
      ];
      $error_message = \Drupal::service('renderer')->renderPlain($render_array);
    }
    else {
      $error_message = reset($errors_new);
    }

    $form_state->setError($element, $error_message);
  }

  // Ensure that errors set prior to calling this method are still shown to the
  // user.
803 804 805
  if (!empty($errors_before)) {
    foreach ($errors_before as $error) {
      \Drupal::messenger()->addError($error);
806 807 808 809 810 811
    }
  }

  return $result;
}

812 813 814 815
/**
 * Saves file uploads to a new location.
 *
 * The files will be added to the {file_managed} table as temporary files.
816 817
 * Temporary files are periodically cleaned. Use the 'file.usage' service to
 * register the usage of the file which will automatically mark it as permanent.
818
 *
819 820 821 822
 * Note that this function does not support correct form error handling. The
 * file upload widgets in core do support this. It is advised to use these in
 * any custom form, instead of calling this function.
 *
823
 * @param string $form_field_name
824 825
 *   A string that is the associative array key of the upload form element in
 *   the form array.
826
 * @param array $validators
827
 *   (optional) An associative array of callback functions used to validate the
828
 *   file. See file_validate() for a full discussion of the array format.
829 830 831 832 833 834 835 836 837 838 839 840
 *   If the array is empty, it will be set up to call file_validate_extensions()
 *   with a safe list of extensions, as follows: "jpg jpeg gif png txt doc
 *   xls pdf ppt pps odt ods odp". To allow all extensions, you must explicitly
 *   set this array to ['file_validate_extensions' => '']. (Beware: this is not
 *   safe and should only be allowed for trusted users, if at all.)
 * @param string|false $destination
 *   (optional) A string containing the URI that the file should be copied to.
 *   This must be a stream wrapper URI. If this value is omitted or set to
 *   FALSE, Drupal's temporary files scheme will be used ("temporary://").
 * @param null|int $delta
 *   (optional) The delta of the file to return the file entity.
 *   Defaults to NULL.
841
 * @param int $replace
842 843
 *   (optional) The replace behavior when the destination file already exists.
 *   Possible values include:
844 845 846 847
 *   - FileSystemInterface::EXISTS_REPLACE: Replace the existing file.
 *   - FileSystemInterface::EXISTS_RENAME: (default) Append
 *     _{incrementing number} until the filename is unique.
 *   - FileSystemInterface::EXISTS_ERROR: Do nothing and return FALSE.
848
 *
849 850 851 852
 * @return array|\Drupal\file\FileInterface|null|false
 *   An array of file entities or a single file entity if $delta != NULL. Each
 *   array element contains the file entity if the upload succeeded or FALSE if
 *   there was an error. Function returns NULL if no file was uploaded.
853 854 855 856
 *
 * @see _file_save_upload_from_form()
 *
 * @todo: move this logic to a service in https://www.drupal.org/node/2244513.
857
 */
858
function file_save_upload($form_field_name, $validators = [], $destination = FALSE, $delta = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
859 860
  static $upload_cache;

861
  $all_files = \Drupal::request()->files->get('files', []);
862
  // Make sure there's an upload to process.
863
  if (empty($all_files[$form_field_name])) {
864 865
    return NULL;
  }
866
  $file_upload = $all_files[$form_field_name];
867 868 869 870 871 872 873 874 875 876 877 878

  // Return cached objects without processing since the file will have
  // already been processed and the paths in $_FILES will be invalid.
  if (isset($upload_cache[$form_field_name])) {
    if (isset($delta)) {
      return $upload_cache[$form_field_name][$delta];
    }
    return $upload_cache[$form_field_name];
  }

  // Prepare uploaded files info. Representation is slightly different
  // for multiple uploads and we fix that here.
879 880
  $uploaded_files = $file_upload;
  if (!is_array($file_upload)) {
881
    $uploaded_files = [$file_upload];
catch's avatar