WP_Image_Editor is incoming!

In WordPress 3.5, GD has been abstracted out of core’s image manipulation functions.
What does that mean for you, you ask?

What’s cool?

  • We add support for Imagick by default, 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 create your own image manipulation engine, or extend ours in plugins to easily add additional functionality to WordPress.

Watch out for:

Any function or filter that receives or returns a GD Image Resource should be avoided if possible, since 3.5 represents core’s move away from GD’s direct use.

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.

Deprecated 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 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 – string; 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()

Need to Deprecate

There isn’t yet an alternative for load_image_to_edit(). This is because there is work towards creating an image container for a future version of WordPress. In the meantime, while decidedly not ideal, I’d suggest doing what core does: wp_get_image_editor( _load_image_to_edit_path( $post_id ) );

How do I use it?

A complete tutorial on the use of WP_Image_Editor is forthcoming, but this should get you started:

$image = wp_get_image_editor( 'cool_image.jpg' );
if ( ! is_wp_error( $image ) ) {
	$image->rotate( 90 );
	$image->resize( 300, 300, true );
	$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

Known issue

#22663 – Non-Square Rotates (non 90*x), followed by a crop, can cause improper results.