PHP frontend to ImageMagick

What is ImageMagick?

ImageMagick is a powerful set of image manipulation utilities. It can read, write and manipulate images in many image formats. It can resize, rotate, sharpen, color reduce or add any other special effect to your images. And, best of all, ImageMagick is directly available from the command line. In this article, we will write a script to make it available from the query string. You can then use it, for example, to automatically generate thumbnails of your images.

What our script will do

We will write a script that we can copy-paste in a directory with images and that enables us to use ImageMagick's convert utility on each of the images in that directory. The script will enable us to give convert commands by changing the query string.

Maybe a simple example will better explain this idea. You've got an image: http://wwww.example.com/img/image.jpg. You copy the ImageMagick script magick.php to the same directory. The image is now also available as http://www.example.com/img/magick.php/image.jpg. So far, your image hasn't changed. Now, imagine you want a thumbnail of the image with a width of exactly 200 pixels. You can get that image by requesting the url: http://www.example.com/img/magick.php/image.jpg?resize(200).

On receiving a request, the script will:

1. Parse the query string;
2. Convert the query string to an ImageMagick command string;
3. Run ImageMagick on the image;
4. Send the modified image to the browser.

As you see, the script will run ImageMagick for every request. This isn't very efficient. As you will probably use just a few commands (e.g. thumbnail and original image) in your html files, caching the output will speed up the system. We will add a point 5 to the list. The output of ImageMagick should be cached. The script should send the cached image if it exists, so ImageMagick won't be generating the same image over and over again.

Commands

You can use the standard commands/options of ImageMagick's convert utility. The command is followed by the command's parameters. These parameters are enclosed in brackets. Multiple commands are separated by a plus sign.

ImageMagick uses < and > in some parameters. You can't use these in html-documents. Instead of < and >, you may use { and } in your query string. The scripts then converts { to < and } to >.

Here are a few example convert commands and their query equivalent.

Extra commands

The long list of ImageMagick commands didn't contain some things I wanted to do. I added three 'extra' commands to the script to do this.

part

The first of these commands is part(<i>width</i>x<i>height</i>). With ImageMagick's crop command, it is possible to get a part of the image. Unfortunately, this command only accepts absolute parameters. It can crop w by h pixels, starting x pixels from the left and y pixels from the top of the image. But what if I want to get 100x100 pixels from the center of the image? That's impossible if I don't know the size of the image.

Enter the part command. It resizes the image to match either the preferred width or the preferred height. Then it crops the image to get the center part of that resized image. And that's what I wanted to do.

colorizehex

ImageMagick's colorize command accepts only decimal RGB numbers, on a 0 to 100 scale. To colorize with red gives

type

The type(<i>type</i>) is available in ImageMagick. It's just not a part of the commands, but is appended to the name of the output file (e.g. jpg:output.jpg). I wanted to include it in the query string, so I made it a command. You can now convert the image to jpeg by using type(jpg) in your query.

Before we start

There are just two minor points left before we can start coding.

Do you have ImageMagick?

ImageMagick should be installed on your system before you can use it in your scripts. This means you will either have to install it yourself, or have your server admin do it for you.

If your server is running PHP in safe mode, which it is likely to be if you're using a (free) shared host, your scripts don't have the right to execute shell commands. As this script runs ImageMagick as a shell command, you won't be able to use it. You could a. ask your hosting provider to disable safe mode or b. use the GD library to generate your images. ImageMagick is far more powerful than the GD library, but you can use the latter even in safe mode.

Why write your own script?

Directly running convert isn't the only way to use ImageMagick in your scripts. The Imagick module from the PEAR library, PerlMagick, a Perl interface to ImageMagick, can do this too. Then why bother and write your own script? Because it gives you a far more flexible system. You just enter your commands as the query string, and the script just sends them to ImageMagick. The PEAR module, for instance, has a special PHP function for each ImageMagick command. The script would have to translate the commands to the corresponding functions, for which it would need an array with all possible commands and functions. The direct method, withouth PEAR module, is therefore faster to write.

The script

And, finally, here's the script that makes it all possible. If you copy all parts, you'll end up with one script. Place it in your image directory, and it's ready for use.

Configuration

You can specify where your images are and where you want the script to cache the processed images. It defaults to the current directory, which is probably where you want it. If the convert utility isn't available in the PATH environment variable of your web server, you'll need to specify the full path.

<?php
//  location of source images (no trailing /)
$image_path = '.';

//  location of cached images (no trailing /)
$cache_path = '.';

//  location of imagemagick's convert utility
$convert_path = 'convert';

Check input

The path and file name of the requested image is available as $_SERVER['PATH_INFO']. We need to check that such information is given, and that the file exists.

// first, check if an image location is given
if (!isset($_SERVER['PATH_INFO'])) {
    die('ERROR: No image specified.');
}
$image = $image_path.$_SERVER['PATH_INFO'];

// next, check if the file exists
if (!file_exists($image)) {
    die('ERROR: That image does not exist.');
}

Parse commands

We need a regular expression to parse the query string and extract commands and parameters.

// extract the commands from the query string
// eg.: ?resize(....)+flip+blur(...)
preg_match_all('/\+*(([a-z]+)(\(([^\)]*)\))?)\+*/',
               $_SERVER['QUERY_STRING'],
               $matches, PREG_SET_ORDER);

We now have an array $matches. Each element in that array is another array, with in the third element (position 2) the command name and on position 4 the parameters.

The cache file name will contain the name of the original file. We then add the commands and parameters to it, so we get an unique name for each version of the image.

// concatenate commands for use in cache file name
$cache = $_SERVER['PATH_INFO'];
foreach ($matches as $match) {
    $cache .= '%'.$match[2].':'.$match[4];
}
$cache = str_replace('/','_',$cache);
$cache = $cache_path.'/'.$cache;
$cache = escapeshellcmd($cache);

Run convert

Now that we have the cache file name, we can look if we already have a cached version of the requested image. If we do, we can just send that to the browser. If we don't, we will ask convert to create it.

We will add each command to the string $commands. We will send that string to convert to generate the image.

if (!file_exists($cache)) {
    // there is no cached image yet, so we'll need to create it first

    // convert query string to an imagemagick command string
    $commands = '';
    foreach ($matches as $match) {
        // $match[2] is the command name
        // $match[4] the parameter
    
        // check input
        if (!preg_match('/^[a-z]+$/',$match[2])) {
            die('ERROR: Invalid command.');
        }
        if (!preg_match('/^[a-z0-9\/{}+-!@%]+$/',$match[4])) {
            die('ERROR: Invalid parameter.');
        }
    
        // replace } with >, { with <
        // > and < could give problems when using html
        $match[4] = str_replace('}','>',$match[4]);
        $match[4] = str_replace('{','<',$match[4]);

After we've checked the input and converted { to < and } to >, we will add this command to the $convert string. But, since we used our own, special commands, we will have to check if this command is one of them. If it is, we will have to do a bit more work.

The colorizehex is quite simple. We will convert hex to decimal, and then convert the 0-255 scale to ImageMagick's 0-100.

        // check for special, scripted commands
        switch ($match[2]) {
            case 'colorizehex':
                // imagemagick's colorize, but with hex-rgb colors
                // convert to decimal rgb
                $r = round((255 - hexdec(substr($match[4], 0, 2))) / 2.55);
                $g = round((255 - hexdec(substr($match[4], 2, 2))) / 2.55);
                $b = round((255 - hexdec(substr($match[4], 4, 2))) / 2.55);
    
                // add command to list
                $commands .= ' -colorize "'."$r/$g/$b".'"';
                break;

The part command requires more work. We first get the size of the source image using the getimagesize() function. After that we let ImageMagick resize the image to match either the new width or the new height. We want one of the image's dimensions to be equal to the new size, and the other one to exceed that size. We can then crop the image to the requested size.

            case 'part':
                // crops the image to the requested size
                if (!preg_match('/^[0-9]+x[0-9]+$/',$match[4])) {
                    die('ERROR: Invalid parameter.');
                }

                list($width, $height) = explode('x', $match[4]);
    
                // get size of the original
                $imginfo = getimagesize($image);
                $orig_w = $imginfo[0];
                $orig_h = $imginfo[1];
    
                // resize image to match either the new width
                // or the new height
    
                // if original width / original height is greater
                // than new width / new height
                if ($orig_w/$orig_h > $width/$height) {
                    // then resize to the new height...
                    $commands .= ' -resize "x'.$height.'"';
    
                    // ... and get the middle part of the new image
                    // what is the resized width?
                    $resized_w = ($height/$orig_h) * $orig_w;
    
                    // crop
                    $commands .= ' -crop "'.$width.'x'.$height.
                                 '+'.round(($resized_w - $width)/2).'+0"';
                } else {
                    // or else resize to the new width
                    $commands .= ' -resize "'.$width.'"';
    
                    // ... and get the middle part of the new image
                    // what is the resized height?
                    $resized_h = ($width/$orig_w) * $orig_h;
    
                    // crop
                    $commands .= ' -crop "'.$width.'x'.$height.
                                 '+0+'.round(($resized_h - $height)/2).'"';
                }
                break;

The type command is really simple. We can just save the type name for now.

            case 'type':
                // convert the image to this file type
                if (!preg_match('/^[a-z]+$/',$match[4])) {
                    die('ERROR: Invalid parameter.');
                }
                $new_type = $match[4];
                break;

If this command isn't special, we can simply add the command and parameters to the command string.

            default:
                // nothing special, just add the command
                if ($match[4]=='') {
                    // no parameter given, eg: flip
                    $commands .= ' -'.$match[2].'';
                } else {
                    $commands .= ' -'.$match[2].' "'.$match[4].'"';
                }
        }
    }

After we've run through the array we've got a list of commands in $commands. We can now run convert. convert needs the commands, the location of the source image and the location of the output image to work. If a new file type is specified, we add that type and a colon to the output file name.

    // create the convert-command
    $convert = $convert_path.' '.$commands.' "'.$image.'" ';
    if (isset($new_type)) {
        // send file type-command to imagemagick
        $convert .= $new_type.':';
    }
    $convert .= '"'.$cache.'"';

    // execute imagemagick's convert, save output as $cache
    exec($convert);
}

Output

The $cache variable should now point to the file containing the requested image. It was already cached or it was generated by convert. If the file exists, we can retrieve some information about that image to put in the http headers.

// there should be a file named $cache now
if (!file_exists($cache)) {
	die('ERROR: Image conversion failed.');
}

// get image data for use in http-headers
$imginfo = getimagesize($cache);
$content_length = filesize($cache);
$last_modified = gmdate('D, d M Y H:i:s',filemtime($cache)).' GMT';

// array of getimagesize() mime types
$getimagesize_mime = array(1=>'image/gif',2=>'image/jpeg',3=>'image/png',
                           4=>'application/x-shockwave-flash',5=>'image/psd',
                           6=>'image/bmp',7=>'image/tiff',8=>'image/tiff',
                           9=>'image/jpeg',
                           13=>'application/x-shockwave-flash',
                           14=>'image/iff');

We can now check if the browser sent us a If-Modified-Since header. This is used to update the browser cache. If the If-Modified-Since date of the browser is equal to the date the image was last modified, we don't have to send the image again. The cache of the browser still has an updated version.

// did the browser send an if-modified-since request?
if (isset($_SERVER['HTTP_IF_MODIFIED_SINCE'])) {
	// parse header
	$if_modified_since = preg_replace('/;.*$/', '', $_SERVER['HTTP_IF_MODIFIED_SINCE']);

	if ($if_modified_since == $last_modified) {
		// the browser's cache is still up to date
		header("HTTP/1.0 304 Not Modified");
		header("Cache-Control: max-age=86400, must-revalidate");
		exit;
	}
}

The browser does really want a (new) version of the image. We send some headers and then the image.

The Content-Type header is a bit special. We have to send a MIME content type, but the PHP getimagesize() command only gives us the number of the image type. With the $getimagesize_mime array we can find the MIME type of that number. In case there is no number we use the application/octet-stream type. I haven't tested that, but it's probably better than text/html. (Note: Starting with PHP 4.3, getimagesize() does return a MIME type. I didn't use it to make the script compatible with older versions.)

// send other headers
header('Cache-Control: max-age=86400, must-revalidate');
header('Content-Length: '.$content_length);
header('Last-Modified: '.$last_modified);
if (isset($getimagesize_mime[$imginfo[2]])) {
	header('Content-Type: '.$getimagesize_mime[$imginfo[2]]);
} else {
	// send generic header
	header('Content-Type: application/octet-stream');
}

// and finally, send the image
readfile($cache);

?>

Concluding

If you copied the parts of the script and saved it in your image directory, it's ready for use. Just enter the url to the script, a slash, then the name of your image and a query string. You should now get the image, modified to suit your needs.

For those of you who don't like to copy-paste: you can download the full script.

Tip

Maybe you don't like the ugly .php part in your url (I don't). You can edit your Apache's configuration file, or place a .htaccess file in your images directory and add the line:

DefaultType application/x-httpd-php

You can then rename the script to something without .php (ie. just magick). The url is now much nicer.