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.jpghttps→ https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600×1064.jpgnetwork_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.
Jetpack 
Sadly, while photon is a good idea, it does not seem to work for me in practice.
I always seem to end up with broken links for some reason where images fail to show up.
LikeLike
Can you provide some examples, or (better yet) open a support ticket on the WordPress.org Jetpack Support Form?
LikeLike
Thanks for quick response!
It’s a new blog I’m setting up.. http://www.theteffect.info/?p=30
I will enable photon.. Go into my hackintosh post.. Both images fail to load…
Tried in safari and Firefox.. Tried clearing cashe then tried from iPad. It’s odd.
If you’re not able, I will submit ticket.. NP
Thanks!
LikeLike
Aha, that happens occasionally when the source image is either too large, or being pulled in from a server responding too slowly to be pulled in before the timeout occurs. We’re actually working on this issue currently, so do check back. For the moment, if you just re-upload the image at a slightly smaller resolution, it will probably start working for you. 🙂
LikeLike
What’s size limit? I think they are 1 or 2 meg images.
LikeLike
It’s not a question of size limit, it’s a question of the server timing out, from what I can tell. The image can’t be fully downloaded in a timely fashion. For example, to download http://www.theteffect.info/wp-content/uploads/2013/07/IMG_0413.jpg from your server, while it is only a 1.7 meg image, it takes me over 10 seconds to download to my laptop — which, as I said, times out.
LikeLike
Is there a reason why when turning on photon, that it does NOT choose already cropped and scaled images as defined in the functions.php? for example, an image.png that’s 1500x2000px. We’ve also got a WordPress cropped image at 200×200 that was created on upload. Rather than using the image-200×200.png, photon is grabbing the original image and adding the query to resize – IE – image.png?w=200&h=200
LikeLike
Retina Displays, primarily. There’s a script we load with photon that will detect if your user is on a Retina display, and then swap out images for the higher-resolution versions. Also, if you are calling any of the filters or anything that modifies the image, pulls it in at different sizes in different places, or the like, it lets us make sure that we’re making the adjustments based on the highest quality source version of the image that we can use.
Does that make sense?
LikeLike
It does make sense when upscaling images, but for my example, I’m not sure how it helps, especially when it does that on the desktop. Not sure if I’m missing your point?
LikeLike
To prevent Photon needing to load, manage, and juggle many different sizes of the same image, we just grab the best version that we can find, and manipulate that single source image for whatever size, crop, or filter happens to be requested at the time. That lets us do cool things, like upscaling for Retina displays, as well. If we just grabbed the 200×200 version, it couldn’t be upscaled to 400×400 for Retina, and if you then wanted to resize it to 175×175, the final quality would be much lower if we use the 200×200 version to resize from, as opposed to resizing it down from the original, larger version.
If it’s still a bit confusing, please drop us a line via the WordPress.org Support Forums, and I’d be happy to continue the discussion there.
LikeLike
exactly my issue! Dont like that it conflicts with my other plugins!!
LikeLike
If you’ve found some plugin conflicts, please do let us know so that we can try to sort them out. 🙂
LikeLike
Maybe a dumb question, but isn’t twentytwelve and twentyeleven (the themes that come with wordpress) have the photon function on their functions.php? I’m trying to implement this on my theme but it seems really confusing, and I thought I could mimic what is written on the official themes. Thanks!
LikeLike
Certainly not that I’m aware of … here’s twentytwelve. Could you poke around and let me know if you can find what you’re thinking of?
LikeLike
Well, my confusion is that I thought that my theme was using photon when it came out, standalone as it is with my theme. But now that I read this post, I figured that if I want photon to work on my site, I need to add the function and edit all the image calls for my particular theme, so it confuses me as to why the wordpress “official” themes have no photon function :/.
Am I correct to say that even though the photon feature was “active” in jetpack, It wasn’t doing anything as there was no photon function nor photon image calls within my theme? As a side note, I know very, very basic PHP, so that’s why I’m looking to browse some examples as to where to put the necessary code. I hope I’m understood haha.
LikeLike
Ah, you’re confusing WordPress.com with WordPress.org. WordPress.org is an open source project, that we contribute to, whereas Photon is a part of the Jetpack service provided by WordPress.com. The naming can be a bit confusing, but we (WordPress.com, Jetpack, call us what you like) don’t control the WordPress.org open source project — we just volunteer time here and there to help out with it. 🙂
This article is strictly relating to images found in your theme itself. Not images in your site’s content. If you’ve posted an image, and it’s in a post, or a page, or a featured image — that’s already being served up through Jetpack. Not to worry! This is just an optional enhancement to let certain images normally bundled with commercial or bespoke themes use our CDN as well.
Does that make a bit more sense?
LikeLike
Ok, now everything is clearer. Thanks a lot. If I wanted to implement this feature, could you explain a bit more in depth where do I use “echo apply_filters( ‘jetpack_photon_url’, get_template_directory_uri() ” call? Thanks, and I know this is for people with theme creating knowledge, but I’m trying to learn.
LikeLike
If you’d like some help using it beyond what’s detailed above (some of the code snippets are a bit cut off and you may need to scroll to see the rest of it), drop us a line on the WordPress.org Support Forums!
Thanks!
LikeLike
Photon is amazing! The free CDN aspect has saved me a lot of money, and I love how it automatically serves up Retina images. Thank you!
LikeLike
Hi
We hope that Jetpack can come up with a plugin that will automatically boost our site with other good quality links to others without the hassle to get us a good Google rating. Wow, that will be good !
Regards * * *Yunus Desai*
a
LikeLike