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

Not 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 2954 (+30 into the body)

   Filters whether to treat the upload bits as an error.

2. 2
   apply_filters( wp_handle_upload )filterline 3012 (+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 ↗

2924function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {2925	if ( ! empty( $deprecated ) ) {2926		_deprecated_argument( __FUNCTION__, '2.0.0' );2927	}2928 2929	if ( empty( $name ) ) {2930		return array( 'error' => __( 'Empty filename' ) );2931	}2932 2933	$wp_filetype = wp_check_filetype( $name );2934	if ( ! $wp_filetype['ext'] && ! current_user_can( 'unfiltered_upload' ) ) {2935		return array( 'error' => __( 'Sorry, you are not allowed to upload this file type.' ) );2936	}2937 2938	$upload = wp_upload_dir( $time );2939 2940	if ( false !== $upload['error'] ) {2941		return $upload;2942	}2943 2944	/**2945	 * Filters whether to treat the upload bits as an error.2946	 *2947	 * Returning a non-array from the filter will effectively short-circuit preparing the upload bits2948	 * and return that value instead. An error message should be returned as a string.2949	 *2950	 * @since 3.0.02951	 *2952	 * @param array|string $upload_bits_error An array of upload bits data, or error message to return.2953	 */2954	$upload_bits_error = apply_filters(2955		'wp_upload_bits',2956		array(2957			'name' => $name,2958			'bits' => $bits,2959			'time' => $time,2960		)2961	);2962	if ( ! is_array( $upload_bits_error ) ) {2963		$upload['error'] = $upload_bits_error;2964		return $upload;2965	}2966 2967	$filename = wp_unique_filename( $upload['path'], $name );2968 2969	$new_file = $upload['path'] . "/$filename";2970	if ( ! wp_mkdir_p( dirname( $new_file ) ) ) {2971		if ( str_starts_with( $upload['basedir'], ABSPATH ) ) {2972			$error_path = str_replace( ABSPATH, '', $upload['basedir'] ) . $upload['subdir'];2973		} else {2974			$error_path = wp_basename( $upload['basedir'] ) . $upload['subdir'];2975		}2976 2977		$message = sprintf(2978			/* translators: %s: Directory path. */2979			__( 'Unable to create directory %s. Is its parent directory writable by the server?' ),2980			$error_path2981		);2982		return array( 'error' => $message );2983	}2984 2985	$ifp = @fopen( $new_file, 'wb' );2986	if ( ! $ifp ) {2987		return array(2988			/* translators: %s: File name. */2989			'error' => sprintf( __( 'Could not write file %s' ), $new_file ),2990		);2991	}2992 2993	fwrite( $ifp, $bits );2994	fclose( $ifp );2995	clearstatcache();2996 2997	// Set correct file permissions.2998	$stat  = @ stat( dirname( $new_file ) );2999	$perms = $stat['mode'] & 0007777;3000	$perms = $perms & 0000666;3001	chmod( $new_file, $perms );3002	clearstatcache();3003

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 7.1.0 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.