Skip to main content

WP_Image_Editor

In WordPress 3.5, GD has been abstracted out of core’s image manipulation functions and has been called WP_Image_Editor. Because of that WordPress also has support for Imagick and that is the default choose. It’s giving better image quality to those who have it available on their host. This is particularly important if you’re using images with extended color profiles, since GD discards them outright.

Imagick support requires Imagick 2.2.0+ compiled against Imagemagick 6.2.9+, for full support. If the required functions aren’t available, WordPress will default back to GD. You can also create your own image manipulation engine, or extend ours in plugins to easily add additional functionality to WordPress. The Gmagick plugin is a good example of creating a additional engine.

Moving to the new functionality

Because of the new class you can’t deal with GD image resources anymore and a lot of stuff has been deprecated.

Deprecated Filters

Several filters have been deprecated, and will no longer function as they did previously. This includes any filter that expected to receive a GD Image Resource, as we can’t pass a GD Image Resource to it if another backend is being used. Instead, new filters are introduced that expect a WP_Image_Editor object.

It’s worth noting that if you’re using these filters, your plugin shouldn’t create a fatal error – it just won’t modify core’s functionality like it used to, and will fail silently.

Renamed Filters

  • image_save_pre is now image_editor_save_pre
  • wp_save_image_file is now wp_save_image_editor_file
  • image_edit_before_change is now wp_image_editor_before_change

While jpeg_quality is backward compatible in 3.5, if you want to change compression quality globally, you should use the filter wp_editor_set_quality in the future, since it applies to other editors and formats that support quality setting as well (like PNG with Imagick). To change the quality on a single image you’re editing, see WP_Image_Editor::set_quality().

New Filters

  • wp_image_editors – modify array to re-order or add additional editor/engine classes.
  • image_editor_default_mime_type – set default mime-type for WP_Image_Editor.

Deprecated Functions

  • wp_load_image() – use wp_get_image_editor() to load files instead.
  • image_resize() – use WP_Image_Editor::resize()
  • gd_edit_image_support() – use wp_image_editor_supports()

How do I use it?

Using the new stuff is easy and you start by using the function wp_get_image_editor(). That will return an WP_Image_Editor object. That can be a GD or an Imagick object. With that you can call all methods that WP_Image_Editor has.

$image = wp_get_image_editor( 'cool_image.jpg' );
if ( ! is_wp_error( $image ) ) {
	$image->rotate( 90 );
	$image->resize( 300, 300, true );
	$image_data = $image->save( 'new_image.jpg' );
}

You can see full class documentation by taking a look at:

wp-includes/class-wp-image-editor.php
wp-includes/class-wp-image-editor-imagick.php
wp-includes/class-wp-image-editor-gd.php

Leave a Reply

Your email address will not be published. Required fields are marked *