Photon and Themes

Theme crafters often ask whether Photon — the free Image Content Delivery Network module in Jetpack — can be used to speed up page loads and save on bandwidth when delivering images from their themes. The short answer: Yes! Read on for the how-to.

If you want to link to a Photon-ized version of an image, whichever way you do it will involve calling jetpack_photon_url().

The jetpack_photon_url() function takes three arguments.

$image_url

(the raw image URL)

$args

(an array of arguments)

$scheme

(whether you want the URL to begin with http://, https://, or if it should be protocol-agnostic by using //)

Let’s address each of these in turn.

$image_url (string) (required)

This one is pretty simple to understand. Just pass in the URL to the image that you’d like to use! For example:

$image_url = get_template_directory_uri() . '/img/logo.png';

$args (array|string) (optional)

$args gives you some fun options to play around with. You can modify the brightness and contrast of your images; color, resize, or crop them; and even apply some filters. (You can view the full documentation for all of the options over on developer.wordpress.com.)

For example, if you wanted to resize an image to 600px wide by 200px tall and make it black and white, we could put two $args together:

$args = array(
	'filter' => 'grayscale',
	'resize' => '600,200',
);

or

$args = 'filter=grayscale&resize=600,200';

$scheme (array) (optional)

Last up is the Scheme. You can ordinarily omit this, and the returned URL will be either http:// or https:// — whichever matches the page the current user is viewing. However, if you need to specify something, here are the values you can pass in and the structure they yield:

• http → http://i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600×1064.jpg
• https → https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600×1064.jpg
• network_path → //i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600×1064.jpg

How to call it safely

Now, when building around any plugin, you’ll always need to consider what happens if the user doesn’t have the plugin! Yes, we know, we too dream of a day when everyone uses Jetpack, but we’ve got to respect the user’s decisions if they choose not to.

As such, you can’t just directly call jetpack_photon_url() in your theme like this:

echo jetpack_photon_url( get_template_directory_uri() . '/img/logo.png' );

(Don’t forget to change this to get_stylesheet_directory_uri() if you’d rather it change for child themes!)

Well, you could, but as soon as they deactivate Jetpack, they would get some nasty errors, and their site could even go down. And nobody wants that!

Fortunately, WordPress has a terrific Filters API. In our next Jetpack release, we’ll be adding in a filter that will let you add this instead:

echo apply_filters( 'jetpack_photon_url', get_template_directory_uri() . '/img/logo.png' );

or

echo apply_filters( 'jetpack_photon_url', get_template_directory_uri() . '/img/logo.png', 'filter=grayscale', 'https' );

And you’re good to go! If Jetpack isn’t installed, then the jetpack_photon_url() function won’t be linked in to the filter, and nothing will happen — but more critically, nothing will break!

Yes, yes, but what do I do until that release?

Oh, you want to use it now? Okay! Just drop this code into your theme’s functions.php

if( function_exists( 'jetpack_photon_url' ) ) {
	add_filter( 'jetpack_photon_url', 'jetpack_photon_url', 10, 3 );
}

It’ll be harmless to leave in once we include it in Jetpack, as the jetpack_photon_url() has a safety valve to make sure it never photon-izes the same URL twice.