wp_upload_bits( string $name, null|string $deprecated, string $bits, string|null $time = null ): array

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$namestring

Filename.

$deprecatednull|string

Never used. Set to null.

$bitsstring

File content

$timestring|nulloptional

Time formatted in 'yyyy/mm'. Default null.Default: null

Return value

array

Information about the newly-uploaded file.

• $filestring

  Filename of the newly-uploaded file.

• $urlstring

  URL of the uploaded file.

• $typestring

  File type.

• $errorstring|false

  Error message, if there has been an error.

Performance profile

How much work a call to wp_upload_bits() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reads or writes the filesystem via fopen().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

13–107

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 158.

Plugin surface

2 hooks

Third-party callbacks on 'wp_upload_bits', 'wp_handle_upload' run inside this call, and their cost is not bounded by anything here.

Called by

2

2 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• filesystemfilesystem accessfopen()called directly
• transienttransientget_transient()one call below wp_upload_bits()

Further down the call graph this can also reach option, cache, query and serialize. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 32 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_upload_bits() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while wp_upload_bits() runs, in this order:

1. 1
   apply_filters( wp_upload_bits )filterline 2919 (+30 into the body)

   Filters whether to treat the upload bits as an error.

2. 2
   apply_filters( wp_handle_upload )filterline 2977 (+88 into the body)

   Filters the data array for the uploaded file.

Uses · 12

• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• __()Retrieves the translation of $text.
• wp_check_filetype()Retrieves the file type from the file name.
• current_user_can()Returns whether the current user has the specified capability.
• wp_upload_dir()Returns an array containing the current upload directory's path and URL.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_unique_filename()Gets a filename that is sanitized and unique for the given directory.
• wp_mkdir_p()Recursive directory creation based on full path.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• wp_basename()i18n-friendly version of basename().
• is_multisite()Determines whether Multisite is enabled.
• clean_dirsize_cache()Cleans directory size cache used by recurse_dirsize().

Used by · 2

• wp_generate_attachment_metadata()Generates attachment meta data and create image sub-sizes for images.
• wp_xmlrpc_server::mw_newMediaObject()Uploads a file, following your settings.

Source code

View on Trac ↗View on GitHub ↗

2889function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {2890	if ( ! empty( $deprecated ) ) {2891		_deprecated_argument( __FUNCTION__, '2.0.0' );2892	}2893 2894	if ( empty( $name ) ) {2895		return array( 'error' => __( 'Empty filename' ) );2896	}2897 2898	$wp_filetype = wp_check_filetype( $name );2899	if ( ! $wp_filetype['ext'] && ! current_user_can( 'unfiltered_upload' ) ) {2900		return array( 'error' => __( 'Sorry, you are not allowed to upload this file type.' ) );2901	}2902 2903	$upload = wp_upload_dir( $time );2904 2905	if ( false !== $upload['error'] ) {2906		return $upload;2907	}2908 2909	/**2910	 * Filters whether to treat the upload bits as an error.2911	 *2912	 * Returning a non-array from the filter will effectively short-circuit preparing the upload bits2913	 * and return that value instead. An error message should be returned as a string.2914	 *2915	 * @since 3.0.02916	 *2917	 * @param array|string $upload_bits_error An array of upload bits data, or error message to return.2918	 */2919	$upload_bits_error = apply_filters(2920		'wp_upload_bits',2921		array(2922			'name' => $name,2923			'bits' => $bits,2924			'time' => $time,2925		)2926	);2927	if ( ! is_array( $upload_bits_error ) ) {2928		$upload['error'] = $upload_bits_error;2929		return $upload;2930	}2931 2932	$filename = wp_unique_filename( $upload['path'], $name );2933 2934	$new_file = $upload['path'] . "/$filename";2935	if ( ! wp_mkdir_p( dirname( $new_file ) ) ) {2936		if ( str_starts_with( $upload['basedir'], ABSPATH ) ) {2937			$error_path = str_replace( ABSPATH, '', $upload['basedir'] ) . $upload['subdir'];2938		} else {2939			$error_path = wp_basename( $upload['basedir'] ) . $upload['subdir'];2940		}2941 2942		$message = sprintf(2943			/* translators: %s: Directory path. */2944			__( 'Unable to create directory %s. Is its parent directory writable by the server?' ),2945			$error_path2946		);2947		return array( 'error' => $message );2948	}2949 2950	$ifp = @fopen( $new_file, 'wb' );2951	if ( ! $ifp ) {2952		return array(2953			/* translators: %s: File name. */2954			'error' => sprintf( __( 'Could not write file %s' ), $new_file ),2955		);2956	}2957 2958	fwrite( $ifp, $bits );2959	fclose( $ifp );2960	clearstatcache();2961 2962	// Set correct file permissions.2963	$stat  = @ stat( dirname( $new_file ) );2964	$perms = $stat['mode'] & 0007777;2965	$perms = $perms & 0000666;2966	chmod( $new_file, $perms );2967	clearstatcache();2968

Changelog

Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.8 tag, from src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.