_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:

1 to 100 of 274
function _wp_handle_upload( &$file, $overrides, $time, $action ) {
  // The default error handler.
  if ( ! function_exists( 'wp_handle_upload_error' ) ) {
    function wp_handle_upload_error( &$file, $message ) {
      return array( 'error' => $message );
    }
  }

  
/**
 * Filters the data for a file before it is uploaded to WordPress.
 *
 * The dynamic portion of the hook name, `$action`, refers to the post action.
 *
 * Possible hook names include:
 *
 *  - `wp_handle_sideload_prefilter`
 *  - `wp_handle_upload_prefilter`
 *
 * @since 2.9.0 as 'wp_handle_upload_prefilter'.
 * @since 4.0.0 Converted to a dynamic hook with `$action`.
 *
 * @param array $file {
 *     Reference to a single element from `$_FILES`.
 *
 *     @type string $name     The original name of the file on the client machine.
 *     @type string $type     The mime type of the file, if the browser provided this information.
 *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
 *     @type int    $size     The size, in bytes, of the uploaded file.
 *     @type int    $error    The error code associated with this file upload.
 * }
 */
  $file = apply_filters( "{$action}_prefilter", $file );

  
/**
 * Filters the override parameters for a file before it is uploaded to WordPress.
 *
 * The dynamic portion of the hook name, `$action`, refers to the post action.
 *
 * Possible hook names include:
 *
 *  - `wp_handle_sideload_overrides`
 *  - `wp_handle_upload_overrides`
 *
 * @since 5.7.0
 *
 * @param array|false $overrides An array of override parameters for this file. Boolean false if none are
 *                               provided. @see _wp_handle_upload().
 * @param array       $file      {
 *     Reference to a single element from `$_FILES`.
 *
 *     @type string $name     The original name of the file on the client machine.
 *     @type string $type     The mime type of the file, if the browser provided this information.
 *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
 *     @type int    $size     The size, in bytes, of the uploaded file.
 *     @type int    $error    The error code associated with this file upload.
 * }
 */
  $overrides = apply_filters( "{$action}_overrides", $overrides, $file );

  // You may define your own function and pass the name in $overrides['upload_error_handler'].
  $upload_error_handler = 'wp_handle_upload_error';
  if ( isset( $overrides['upload_error_handler'] ) ) {
    $upload_error_handler = $overrides['upload_error_handler'];
  }

  // You may have had one or more 'wp_handle_upload_prefilter' functions error out the file. Handle that gracefully.
  if ( isset( $file['error'] ) && ! is_numeric( $file['error'] ) && $file['error'] ) {
    return call_user_func_array( $upload_error_handler, array( &$file, $file['error'] ) );
  }

  // Install user overrides. Did we mention that this voids your warranty?

  // You may define your own function and pass the name in $overrides['unique_filename_callback'].
  $unique_filename_callback = null;
  if ( isset( $overrides['unique_filename_callback'] ) ) {
    $unique_filename_callback = $overrides['unique_filename_callback'];
  }

  /*
	 * This may not have originally been intended to be overridable,
	 * but historically has been.
	 */
  if ( isset( $overrides['upload_error_strings'] ) ) {
    $upload_error_strings = $overrides['upload_error_strings'];
  } else {
    // Courtesy of php.net, the strings that describe the error indicated in $_FILES[{form field}]['error'].
    $upload_error_strings = array(
      false,
      sprintf(
        /* translators: 1: upload_max_filesize, 2: php.ini */
        __( 'The uploaded file exceeds the %1$s directive in %2$s.' ),
        'upload_max_filesize',
        'php.ini'
      ),
      sprintf(
        /* translators: %s: MAX_FILE_SIZE */
        __( 'The uploaded file exceeds the %s directive that was specified in the HTML form.' ),
        'MAX_FILE_SIZE'
      ),
      __( 'The uploaded file was only partially uploaded.' ),
 

 View on GitHub View on Trac