wp_save_image_file( string $filename, WP_Image_Editor $image, string $mime_type, int $post_id ): array|WP_Error|bool

Compatibility

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

Parameters

$filenamestring

Name of the file to be saved.

$imageWP_Image_Editor

The image editor instance.

$mime_typestring

The mime type of the image.

$post_idint

Attachment post ID.

Return value

array|WP_Error|bool

Array on success or WP_Error if the file failed to save. When called with a deprecated value for the $image parameter, i.e. a non-WP_Image_Editor image resource or GdImage instance, the function will return true on success, false on failure.

• $pathstring

  Path to the image file.

• $filestring

  Name of the image file.

• $widthint

  Image width.

• $heightint

  Image height.

• $mime-typestring

  The mime type of the image.

• $filesizeint

  File size of the image.

Performance profile

How much work a call to wp_save_image_file() 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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

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

Instructions

24–62

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

Plugin surface

5 hooks

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

Called by

1

1 place 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

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

What one call costs · 9 distinct outcomes

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

Hooks and filters fired · 5

5 hooks fire while wp_save_image_file() runs, in this order:

1. 1
   apply_filters( image_editor_save_pre )filterline 434 (+4 into the body)

   Filters the WP_Image_Editor instance for the image to be streamed to the browser.

2. 2
   apply_filters( wp_save_image_editor_file )filterline 450 (+20 into the body)

   Filters whether to skip saving the image file.

3. 3
   do_action( image_save_pre )filter_deprecatedline 462 (+32 into the body)

   Filters the GD image resource to be streamed to the browser.

4. 4
   do_action( wp_save_image_file )filter_deprecatedline 479 (+49 into the body)

   Filters whether to skip saving the image file.

5. 5
   apply_filters( jpeg_quality )filterline 493 (+63 into the body)

   Filters the JPEG compression quality for backward-compatibility.

Uses · 4

• apply_filters()Calls the callback functions that have been added to a filter hook.
• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• __()Retrieves the translation of $text.
• apply_filters_deprecated()Fires functions attached to a deprecated filter hook.

Used by · 1

• wp_save_image()Saves image to post, along with enqueued changes in `$_REQUEST['history']`.

Source code

View on Trac ↗View on GitHub ↗

430function wp_save_image_file( $filename, $image, $mime_type, $post_id ) {431	if ( $image instanceof WP_Image_Editor ) {432 433		/** This filter is documented in wp-admin/includes/image-edit.php */434		$image = apply_filters( 'image_editor_save_pre', $image, $post_id );435 436		/**437		 * Filters whether to skip saving the image file.438		 *439		 * Returning a non-null value will short-circuit the save method,440		 * returning that value instead.441		 *442		 * @since 3.5.0443		 *444		 * @param bool|null       $override  Value to return instead of saving. Default null.445		 * @param string          $filename  Name of the file to be saved.446		 * @param WP_Image_Editor $image     The image editor instance.447		 * @param string          $mime_type The mime type of the image.448		 * @param int             $post_id   Attachment post ID.449		 */450		$saved = apply_filters( 'wp_save_image_editor_file', null, $filename, $image, $mime_type, $post_id );451 452		if ( null !== $saved ) {453			return $saved;454		}455 456		return $image->save( $filename, $mime_type );457	} else {458		/* translators: 1: $image, 2: WP_Image_Editor */459		_deprecated_argument( __FUNCTION__, '3.5.0', sprintf( __( '%1$s needs to be a %2$s object.' ), '$image', 'WP_Image_Editor' ) );460 461		/** This filter is documented in wp-admin/includes/image-edit.php */462		$image = apply_filters_deprecated( 'image_save_pre', array( $image, $post_id ), '3.5.0', 'image_editor_save_pre' );463 464		/**465		 * Filters whether to skip saving the image file.466		 *467		 * Returning a non-null value will short-circuit the save method,468		 * returning that value instead.469		 *470		 * @since 2.9.0471		 * @deprecated 3.5.0 Use {@see 'wp_save_image_editor_file'} instead.472		 *473		 * @param bool|null        $override  Value to return instead of saving. Default null.474		 * @param string           $filename  Name of the file to be saved.475		 * @param resource|GdImage $image     Image resource or GdImage instance.476		 * @param string           $mime_type The mime type of the image.477		 * @param int              $post_id   Attachment post ID.478		 */479		$saved = apply_filters_deprecated(480			'wp_save_image_file',481			array( null, $filename, $image, $mime_type, $post_id ),482			'3.5.0',483			'wp_save_image_editor_file'484		);485 486		if ( null !== $saved ) {487			return $saved;488		}489 490		switch ( $mime_type ) {491			case 'image/jpeg':492				/** This filter is documented in wp-includes/class-wp-image-editor.php */493				return imagejpeg( $image, $filename, apply_filters( 'jpeg_quality', 90, 'edit_image' ) );494			case 'image/png':495				return imagepng( $image, $filename );496			case 'image/gif':497				return imagegif( $image, $filename );498			case 'image/webp':499				if ( function_exists( 'imagewebp' ) ) {500					return imagewebp( $image, $filename );501				}502				return false;503			case 'image/avif':504				if ( function_exists( 'imageavif' ) ) {505					return imageavif( $image, $filename );506				}507				return false;508			default:509				return false;

Changelog

Introduced in 2.9.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-admin/includes/image-edit.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.