wp_get_image_editor()
Returns a WP_Image_Editor object with the specified image. Used for resizing an image (creating thumbnails) and editing the image.
Various actions can be performed on the image: scale down, rotate, flip, etc. All of this is done via the methods of the WP_Image_Editor class.
The edited image can easily be saved to a specified location, see example.
The WP_Image_Editor class is located in the file: /wp-includes/class-wp-image-editor.php
No Hooks.
Returns
WP_Image_Editor|WP_Error. WP_Image_Editor object or a WP_Error object if the image could not be obtained from the passed URL or another error.
Usage
$image_editor = wp_get_image_editor( $path, $args );
- $path(string) (required)
- Path to the original image on which the copy will be created.
- $args(array)
- Additional data. Accepts: the image mime type and methods: mime_type, methods.
Default: array()
Examples
#1 Create a thumbnail of the image
Let's assume we have an image '/wp-content/uploads/2014/02/uka.png' (it is on our server). This example shows how to create a reduced copy of this image using the WP_Image_Editor class:
$file_path = $_SERVER['DOCUMENT_ROOT'] . '/wp-content/uploads/2014/02/uka.png';
// load the object
$image = wp_get_image_editor( $file_path );
// you can specify the URL instead of the absolute path:
// $image = wp_get_image_editor( 'http://wp-kama.ru/wp-content/uploads/2014/02/uka.png' );
// process the image
if ( ! is_wp_error( $image ) ) {
// rotate the image by 90 degrees
$image->rotate( 90 );
// resize it to 80x80
$image->resize( 80, 80, true );
// save in the same folder as the current file, with the name {name}-{suffix}.{ext}
$new_file_path = $image->generate_filename();
// save in the root of the site as new_image.png
$image->save( $new_file_path );
}
Class methods that can be used to modify the image
You should not use the editor class directly; it's better to always use this function - wp_get_image_editor(), which is a wrapper for the WP_Image_Editor class.
Methods of WP_Image_Editor
- WP_Image_Editor::supports_mime_type( $mime_type )
- Checks whether the editor supports the specified mime type.
- WP_Image_Editor::save( $destfilename = null, $mime_type = null )
- Saves the current image to a file.
- WP_Image_Editor::resize( $max_w, $max_h, $crop = false )
Resizes the current image.
The $crop parameter determines whether the image should be cropped when reducing its size and how to crop it. Possible values for $crop:
- false (default) - the image will not be cropped, but will be scaled down proportionally as is.
- true - it will be cropped to the specified dimensions from the center of the image.
- array - the image will be cropped to the specified dimensions within a specified area. The area is specified as an array array( x_crop_position, y_crop_position ):
x_crop_position- can be: 'left', 'center', or 'right'.y_crop_position- can be: 'top', 'center', or 'bottom'.
- WP_Image_Editor::multi_resize( $sizes )
- Processes the current image and saves several specified sizes to disk at once from a single processed image.
- WP_Image_Editor::crop( $src_x, $src_y, $src_w, $src_h, $dst_w = null, $dst_h = null, $src_abs = false )
- Crops the image.
- WP_Image_Editor::rotate( $angle )
- Rotates current image counter-clockwise by $angle.
- WP_Image_Editor::flip( $horz, $vert )
- Flips the image horizontally, vertically, or both.
- WP_Image_Editor::stream( $mime_type = null )
- Outputs the current image to the browser.
- WP_Image_Editor::get_size()
- Gets the image dimensions as an array with keys: 'width' and 'height'.
- WP_Image_Editor::update_size( $width = null, $height = null )
- Sets the size of the current image.
- WP_Image_Editor::set_quality( $quality )
- Sets the compression quality for JPG files. An integer from 1 to 100 is specified, which corresponds to percentages: 100% - best quality, 50% - poor quality, but strong compression and smaller file size.
Default: 90 - WP_Image_Editor::get_output_format( $filename = null, $mime_type = null )
- Retrieves the preferred mime type and extension based on the file extension or mime type. By default, it uses the value of the $this->default_mime_type property when the specified format is not supported.
- WP_Image_Editor::generate_filename( $suffix = null, $dest_path = null, $extension = null )
- Generates the final filename based on the current file and the size-related suffix.
- WP_Image_Editor::get_suffix()
- Builds and returns the suffix for the filename based on width and height.
- WP_Image_Editor::make_image( $filename, $function, $arguments )
- Calls the editor's save function or processes the file when $filename is passed as a stream. In $function and $arguments, one of the functions is usually specified: imagegif(), imagepng(), imagejpeg() and its parameters.
- WP_Image_Editor::get_mime_type( $extension = null )
- Gets the mime type for the specified extension, e.g. jpg. See wp_get_mime_types().
- WP_Image_Editor::get_extension( $mime_type = null )
- Gets the extension for the specified mime type. See wp_get_mime_types().
Changelog
| Since 3.5.0 | Introduced. |