function file_save_upload

Saves file uploads to a new location.

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.

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.

@todo: move this logic to a service in https://www.drupal.org/node/2244513.

Parameters

string $form_field_name: A string that is the associative array key of the upload form element in the form array.

array $validators: (optional) An associative array of callback functions used to validate the file. See file_validate() for a full discussion of the array format. 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.)

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://").

null|int $delta: (optional) The delta of the file to return the file entity. Defaults to NULL.

int $replace: (optional) The replace behavior when the destination file already exists. Possible values include:

• 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.

Return value

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.

See also

_file_save_upload_from_form()

File

core/modules/file/file.module, line 909

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

Code

function file_save_upload($form_field_name, $validators = [], $destination = FALSE, $delta = NULL, $replace = FileSystemInterface::EXISTS_RENAME) {
  static $upload_cache;
  $all_files = \Drupal::request()->files
    ->get('files', []);

  // Make sure there's an upload to process.
  if (empty($all_files[$form_field_name])) {
    return NULL;
  }
  $file_upload = $all_files[$form_field_name];

  // 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.
  $uploaded_files = $file_upload;
  if (!is_array($file_upload)) {
    $uploaded_files = [
      $file_upload,
    ];
  }
  $files = [];
  foreach ($uploaded_files as $i => $file_info) {
    $files[$i] = _file_save_upload_single($file_info, $form_field_name, $validators, $destination, $replace);
  }

  // Add files to the cache.
  $upload_cache[$form_field_name] = $files;
  return isset($delta) ? $files[$delta] : $files;
}