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.

@internal 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.

Parameters

array $element: The FAPI element whose values are being saved.

\Drupal\Core\Form\FormStateInterface $form_state: The current state of the form.

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

\Drupal\Core\File\FileExists|int $fileExists: (optional) The replace behavior when the destination file already exists.

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.

Throws

\ValueError Thrown if $fileExists is a legacy int and not a valid value.

See also

https://www.drupal.org/project/drupal/issues/3069020

https://www.drupal.org/project/drupal/issues/2482783

5 calls to _file_save_upload_from_form()

FileTestSaveUploadFromForm::validateForm in core/modules/file/tests/file_test/src/Form/FileTestSaveUploadFromForm.php

Form validation handler.

file_managed_file_save_upload in core/modules/file/file.module

Saves any files that have been uploaded into a managed_file element.

ImportForm::validateForm in core/modules/locale/src/Form/ImportForm.php

Form validation handler.

SettingsForm::validateForm in core/modules/navigation/src/Form/SettingsForm.php

Form validation handler.

ThemeSettingsForm::validateForm in core/modules/system/src/Form/ThemeSettingsForm.php

Form validation handler.

File

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

Code

function _file_save_upload_from_form(array $element, FormStateInterface $form_state, $delta = NULL, FileExists|int $fileExists = FileExists::Rename) {
  if (!$fileExists instanceof FileExists) {
    // @phpstan-ignore staticMethod.deprecated
    $fileExists = FileExists::fromLegacyInt($fileExists, __METHOD__);
  }
  // Get all errors set before calling this method. This will also clear them
  // from the messenger service.
  $errors_before = \Drupal::messenger()->deleteByType(MessengerInterface::TYPE_ERROR);
  $upload_location = $element['#upload_location'] ?? FALSE;
  $upload_name = implode('_', $element['#parents']);
  $upload_validators = $element['#upload_validators'] ?? [];
  $result = file_save_upload($upload_name, $upload_validators, $upload_location, $delta, $fileExists);
  // Get new errors that are generated while trying to save the upload. This
  // will also clear them from the messenger service.
  $errors_new = \Drupal::messenger()->deleteByType(MessengerInterface::TYPE_ERROR);
  if (!empty($errors_new)) {
    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')->renderInIsolation($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.
  if (!empty($errors_before)) {
    foreach ($errors_before as $error) {
      \Drupal::messenger()->addError($error);
    }
  }
  return $result;
}

---