_wp_handle_upload() – Handles PHP uploads in WordPress.

You appear to be a bot. Output may be restricted

Description

Handles PHP uploads in WordPress.

Sanitizes file names, checks extensions for mime type, and moves the file to the appropriate directory within the uploads directory.

Usage

$array = _wp_handle_upload( $file, $overrides, $time, $action );

Parameters

$file
( array ) required – { Reference to a single element from `$_FILES`. Call the function once for each uploaded file.
$name
( string ) required – The original name of the file on the client machine.
$type
( string ) required – The mime type of the file, if the browser provided this information.
$tmp_name
( string ) required – The temporary filename of the file in which the uploaded file was stored on the server.
$size
( int ) required – The size, in bytes, of the uploaded file.
$error
( int ) required – The error code associated with this file upload. }
$overrides
( array|false ) required – { An array of override parameters for this file, or boolean false if none are provided.
$upload_error_handler
( callable ) required – Function to call when there is an error during the upload process.
$unique_filename_callback
( callable ) required – Function to call when determining a unique file name for the file.
$upload_error_strings
( string[] ) required – The strings that describe the error indicated in `$_FILES[{form field}]['error']`.
$test_form
( bool ) required – Whether to test that the $_POST['action'] parameter is as expected.
$test_size
( bool ) required – Whether to test that the file size is greater than zero bytes.
$test_type
( bool ) required – Whether to test that the mime type of the file is as expected.
$mimes
( string[] ) required – Array of allowed mime types keyed by their file extension regex. }
$time
( string ) required – Time formatted in 'yyyy/mm'.
$action
( string ) required – Expected value for `$_POST['action']`.
$file
( string ) required – Filename of the newly-uploaded file.
$url
( string ) required – URL of the newly-uploaded file.
$type
( string ) required – Mime type of the newly-uploaded file. }

Returns

array { On success, returns an associative array of file attributes. On failure, returns $overrides['upload_error_handler']( &$file, $message ) or `array( 'error' => $message )`.

Source

File name: wordpress/wp-admin/includes/file.php
Lines:

101 to 200 of 274
      __( 'No file was uploaded.' ),
      '',
      __( 'Missing a temporary folder.' ),
      __( 'Failed to write file to disk.' ),
      __( 'File upload stopped by extension.' ),
    );
  }

  // All tests are on by default. Most can be turned off by $overrides[{test_name}] = false;
  $test_form = isset( $overrides['test_form'] ) ? $overrides['test_form'] : true;
  $test_size = isset( $overrides['test_size'] ) ? $overrides['test_size'] : true;

  // If you override this, you must provide $ext and $type!!
  $test_type = isset( $overrides['test_type'] ) ? $overrides['test_type'] : true;
  $mimes     = isset( $overrides['mimes'] ) ? $overrides['mimes'] : false;

  // A correct form post will pass this test.
  if ( $test_form && ( ! isset( $_POST['action'] ) || $_POST['action'] !== $action ) ) {
    return call_user_func_array( $upload_error_handler, array( &$file, __( 'Invalid form submission.' ) ) );
  }

  // A successful upload will pass this test. It makes no sense to override this one.
  if ( isset( $file['error'] ) && $file['error'] > 0 ) {
    return call_user_func_array( $upload_error_handler, array( &$file, $upload_error_strings[ $file['error'] ] ) );
  }

  // A properly uploaded file will pass this test. There should be no reason to override this one.
  $test_uploaded_file = 'wp_handle_upload' === $action ? is_uploaded_file( $file['tmp_name'] ) : @is_readable( $file['tmp_name'] );
  if ( ! $test_uploaded_file ) {
    return call_user_func_array( $upload_error_handler, array( &$file, __( 'Specified file failed upload test.' ) ) );
  }

  $test_file_size = 'wp_handle_upload' === $action ? $file['size'] : filesize( $file['tmp_name'] );
  // A non-empty file will pass this test.
  if ( $test_size && ! ( $test_file_size > 0 ) ) {
    if ( is_multisite() ) {
      $error_msg = __( 'File is empty. Please upload something more substantial.' );
    } else {
      $error_msg = sprintf(
        /* translators: 1: php.ini, 2: post_max_size, 3: upload_max_filesize */
        __( 'File is empty. Please upload something more substantial. This error could also be caused by uploads being disabled in your %1$s file or by %2$s being defined as smaller than %3$s in %1$s.' ),
        'php.ini',
        'post_max_size',
        'upload_max_filesize'
      );
    }

    return call_user_func_array( $upload_error_handler, array( &$file, $error_msg ) );
  }

  // A correct MIME type will pass this test. Override $mimes or use the upload_mimes filter.
  if ( $test_type ) {
    $wp_filetype     = wp_check_filetype_and_ext( $file['tmp_name'], $file['name'], $mimes );
    $ext             = empty( $wp_filetype['ext'] ) ? '' : $wp_filetype['ext'];
    $type            = empty( $wp_filetype['type'] ) ? '' : $wp_filetype['type'];
    $proper_filename = empty( $wp_filetype['proper_filename'] ) ? '' : $wp_filetype['proper_filename'];

    // Check to see if wp_check_filetype_and_ext() determined the filename was incorrect.
    if ( $proper_filename ) {
      $file['name'] = $proper_filename;
    }

    if ( ( ! $type || ! $ext ) && ! current_user_can( 'unfiltered_upload' ) ) {
      return call_user_func_array( $upload_error_handler, array( &$file, __( 'Sorry, you are not allowed to upload this file type.' ) ) );
    }

    if ( ! $type ) {
      $type = $file['type'];
    }
  } else {
    $type = '';
  }

  /*
	 * A writable uploads dir will pass this test. Again, there's no point
	 * overriding this one.
	 */
  $uploads = wp_upload_dir( $time );
  if ( ! ( $uploads && false === $uploads['error'] ) ) {
    return call_user_func_array( $upload_error_handler, array( &$file, $uploads['error'] ) );
  }

  $filename = wp_unique_filename( $uploads['path'], $file['name'], $unique_filename_callback );

  // Move the file to the uploads dir.
  $new_file = $uploads['path'] . "/$filename";

  
/**
 * Filters whether to short-circuit moving the uploaded file after passing all checks.
 *
 * If a non-null value is returned from the filter, moving the file and any related
 * error reporting will be completely skipped.
 *
 * @since 4.9.0
 *
 * @param mixed    $move_new_file If null (default) move the file after the upload.
 * @param array    $file          {
 *     Reference to a single element from `$_FILES`.
 *
 *     @type string $name     The original name of the file on the client machine.
 

 View on GitHub View on Trac