Temporary internal function _file_save_upload_from_form() wraps file_save_upload() to support Inline Form Errors

To be able to mark a file upload field as having an error, a temporary internal function has been introduced to save the uploaded file.

Used before 8.4.0:

file_save_upload($form_field_name, $validators = array(), $destination = FALSE, $delta = NULL, $replace = FILE_EXISTS_RENAME)

New deprecated internal function in 8.4.0:

_file_save_upload_from_form($element, FormStateInterface $form_state, $delta = NULL, $replace = FILE_EXISTS_RENAME)

Usage warning!

This function should not be used except for internal Drupal Core usage. To support inline form errors for a file upload use the file and image upload widgets / render elements provided in core.

Background

The original file_save_upload() didn't include $form_state, and thus file upload fields where not marked as having an error. This also prevented Inline Form Errors from displaying the error below the field. In case of a required field, additionally an unhelpful constraint message was shown.

Saving file uploads should always happen before form submit handlers are called. Because if form validation passed, but the file upload fails, the user can't fix his mistake or problem. In the submit handler the upload can be made permanent.

Upload validators and destination should be set as properties of the render element $element when needed: #upload_validators and #upload_location respectively.

For example:

  $element = [
      '#type' => 'file',
      '#title' => $this->t('Translation file'),
      '#description' => [
        '#theme' => 'file_upload_help',
        '#description' => $this->t('A Gettext Portable Object file.'),
        '#upload_validators' => $validators,
      ],
      '#upload_validators' => $validators,
      '#upload_location' => 'translations://',
    ];