Upload: Introduce the {$action}_overrides filter that allows the overrides parameter for file uploads and file sideloads to be filtered.

The dynamic portion of the hook name, `$action`, refers to the post action.

Props iandunn, jakub.tyrcha, nacin, wonderboymusic, Mte90, johnbillion

Fixes #16849

Built from https://develop.svn.wordpress.org/trunk@49845


git-svn-id: http://core.svn.wordpress.org/trunk@49564 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/file.php

@@ -725,8 +725,20 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
  *
  * @param string[]       $file      Reference to a single element of `$_FILES`.
  *                                  Call the function once for each uploaded file.
- * @param string[]|false $overrides An associative array of names => values
- *                                  to override default variables. Default false.
+ * @param array|false    $overrides {
+ *     An array of override parameters for this file, or boolean false if none are provided.
+ *
+ *     @type callable $upload_error_handler     Function to call when there is an error during the upload process.
+ *                                              @see wp_handle_upload_error().
+ *     @type callable $unique_filename_callback Function to call when determining a unique file name for the file.
+ *                                              @see wp_unique_filename().
+ *     @type string[] $upload_error_strings     The strings that describe the error indicated in
+ *                                              `$_FILES[{form field}]['error']`.
+ *     @type bool     $test_form                Whether to test that the `$_POST['action]` parameter is as expected.
+ *     @type bool     $test_size                Whether to test that the file size is greater than zero bytes.
+ *     @type bool     $test_type                Whether to test that the mime type of the file is as expected.
+ *     @type string[] $mimes                    Array of allowed mime types keyed by their file extension regex.
+ * }
  * @param string         $time      Time formatted in 'yyyy/mm'.
  * @param string         $action    Expected value for `$_POST['action']`.
  * @return string[] On success, returns an associative array of file attributes.
@@ -745,14 +757,35 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
 	 * 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 filter 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 string[] $file An array of data for a single file.
+	 * @param string[] $file An array of data for the file. Reference to a single element of `$_FILES`.
 	 */
 	$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 filter 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 string[]    $file      An array of data for the file. Reference to a single element of `$_FILES`.
+	 */
+	$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'] ) ) {

wp-admin/includes/media.php

@@ -430,7 +430,7 @@ function media_handle_upload( $file_id, $post_id, $post_data = array(), $overrid
  * @since 2.6.0
  * @since 5.3.0 The `$post_id` parameter was made optional.
  *
- * @param array  $file_array Array similar to a `$_FILES` upload array.
+ * @param array  $file_array Array that represents a `$_FILES` upload array.
  * @param int    $post_id    Optional. The post ID the media is associated with.
  * @param string $desc       Optional. Description of the side-loaded file. Default null.
  * @param array  $post_data  Optional. Post data to override. Default empty array.

wp-includes/functions.php

@@ -2791,7 +2791,7 @@ function wp_ext2type( $ext ) {
  * @since 2.0.4
  *
  * @param string   $filename File name or path.
- * @param string[] $mimes    Optional. Array of mime types keyed by their file extension regex.
+ * @param string[] $mimes    Optional. Array of allowed mime types keyed by their file extension regex.
  * @return array {
  *     Values for the extension and mime type.
  *
@@ -2833,7 +2833,7 @@ function wp_check_filetype( $filename, $mimes = null ) {
  * @param string   $file     Full path to the file.
  * @param string   $filename The name of the file (may differ from $file due to $file being
  *                           in a tmp directory).
- * @param string[] $mimes    Optional. Array of mime types keyed by their file extension regex.
+ * @param string[] $mimes    Optional. Array of allowed mime types keyed by their file extension regex.
  * @return array {
  *     Values for the extension, mime type, and corrected filename.
  *

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.7-alpha-49844';
+$wp_version = '5.7-alpha-49845';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.