When WordPress 4.7 was released at the end of 2016 most of the response was around the new REST API endpoints for posts, comments, terms, users, meta, and settings. However, it was one of the new smaller features that caught my eye: PDF preview images.
In this post I’ll take you through what that entails, why it’s useful, and how to get it set up on your own site.
Real World Use
The new feature means WordPress now has the ability to create an image from the first page of a PDF when it is uploaded to the Media Library, as long as your server has the necessary requirements (more on that later). The release post boasts that the new feature allows you to “more easily distinguish between all your documents”, however I instantly recognized a better use for the preview image.
For the last 4 years my wife has been running an educational resources website which allows teachers and parents to download free PDF teaching resources. Naturally I was roped in to build and maintain the site! It runs on WordPress (of course) and is powered by Easy Digital Downloads. Every time she adds a new resource, the workflow includes:
- Create the PDF resource
- Use a program to generate an image from the first page
- Add the PDF file to a new EDD Download
- Add the image as the Download’s featured image
This is an unnecessarily lengthy process, which she has had to do over 600 times!
Back when I built the site, I was aware there were libraries that could automate this on the site, but I was hamstrung by cheap shared hosting and limited by my own sysadmin abilities. It was an improvement I always intended to add, and when I saw Mike Schroder’s post on the Make WordPress blog, I knew it was time to implement it.
Requirements
This feature relies on some specific packages that need to be installed on your server or development environment:
ImageMagick is software that can create, edit, compose, or convert bitmap images, as well as reading and writing images in over 200 formats, including PDF. Imagick is the slightly confusingly named PHP extension to communicate with ImageMagick via PHP. Finally, Ghostscript is an interpreter for the PostScript language and for PDF.
Installation
These software packages might not be installed by default on servers and won’t be typically found on shared hosting. However, if you manage your own servers or use a decent managed WordPress host then you should be able to get set up. To test out the new WordPress feature, and integrate it into the site, I first needed to get set up on my local development environment.
MAMP
As of MAMP PRO 4, support for ImageMagick is baked in. You can enable it from the extensions list on the PHP settings screen:
However, as I’m still running version 3.5, I had to do it all manually. But I was pleasantly surprised to find (despite my shortcomings as a sysadmin) that I managed to get this all installed and configured easily. Then again, things are a lot easier when you can use awesome tools like Homebrew!
First of all we need to get the necessary software installed on our machine:
brew update
brew install ghostscript
brew install ImageMagick --with-ghostscript
Then you can check the installation has worked by running the following, and seeing pdf in the table of delegates:
convert -list delegate
Now we need to tell PHP to work with ImageMagick. When talking to PHP on the command line we want to make sure we are using MAMP’s version of PHP. To do that, you can either run commands prefixed with the explicit MAMP directory for PHP, like /Applications/MAMP/bin/php/php5.5.26/bin/php or configure Terminal to always use MAMP’s version when running the php command.
Let’s install the Imagick extension using PECL, which comes bundled with MAMP:
pecl install imagick
Finally we need to enable the extension in the php.ini file by adding extension=imagick.so somewhere. (I added it to the ‘Dynamic Modules’ section.) You can use File > Edit Template if you are using MAMP PRO, or run php --ini | grep "Loaded Configuration File” to locate the file and edit it there.
Once that’s all done, stop and start MAMP and you can test the whole installation by running:
php -r "var_export(class_exists('imagick'));"
That should print out true for a successful response. I used this excellent guide to help me along the way, which has troubleshooting tips for most stages of the process.
Ubuntu
The site is hosted on a Digital Ocean droplet built by following this fantastic hosting series from Ashley, running on Ubuntu 14 with PHP 7. You will need to tweak the PHP version number below depending on your environment:
sudo apt-get update
sudo apt-get php7.0-imagick
Finally restart your PHP service, in my case I ran:
sudo service php-fpm7.0 restart
I also installed the Debug Media plugin, which extends Debug Bar, to tell me if all the requirements are installed correctly and which versions.
Using the Preview Image
With everything installed, WordPress should be creating an image for each PDF you upload:
Like I said, this is nice for previewing PDFs in the dashboard, but I needed to do a little more with the image, and display it on the frontend of the site. It’s actually really straightforward to get the image of the PDF to be used wherever. If you know the ID of the PDF attachment, then to retrieve the image in any size is as simple as:
$image = wp_get_attachment_image( $attachment_id, 'large' );
However, in my case the image of the PDF was going to be used instead of a Download’s featured image. The Download is a custom post type that EDD uses, which can have multiple downloadable files. I ended up writing a little helper function to grab the image of the first file, when passing in a Download ID, but using the featured image if it has one:
function get_download_image( $id, size = 'large' ) {
if ( has_post_thumbnail( $id ) ) {
return get_the_post_thumbnail( $id, $size );
}
if ( ! function_exists( 'edd_get_download_files' ) ) {
return '';
}
$files = edd_get_download_files( $id );
foreach ( $files as $file ) {
if ( empty( $file['attachment_id'] ) ) {
continue;
}
$image = wp_get_attachment_image( $file['attachment_id'], $size );
if ( $image ) {
return $image;
}
}
return '';
}
The More You Know
Although my helper function uses the featured image for existing downloads, I did consider trying to get WordPress to generate the preview images for all of the PDFs already on the site. If you want to retrospectively generate preview images then WP-CLI is your friend! As of version 1.0.1, you can use the wp media regenerate command which will process PDF attachments and generate the preview image.
In the future I intend to move all media (PDFs and images) off the server to Amazon S3 and use CloudFront as a CDN. Naturally I will be using WP Offload S3 for the job, which works seamlessly with the new PDF preview image feature since version 1.3.1.
There might be a time when you don’t actually want an image generated for each PDF uploaded to your library. After all, the preview image isn’t just one file – there’s an image file for every image size. This could be a significant amount of images that need to be created during the upload process, and need to be stored on the server.
Turning off the preview image feature is very simple. Just add the following to an mu-plugin, or regular plugin:
add_filter( ‘fallback_intermediate_image_sizes’, ‘__return_empty_array’ );
Conclusion
PDF preview images is a really nice enhancement to WordPress, and something I could instantly use and see the benefit from. It’s really made a difference to how my wife runs the site, significantly reducing the time it takes to add new resources. It just goes to show that sometimes the smaller improvements can be the most helpful.
Have you used this new feature yourself? Have you found any smaller features in WordPress core really helpful? Let me know in the comments below.
