View Comments ( 6 )

Image Manipulation with phpThumbOf in MODx Revolution

June 23, 2011 | Tags for this entry: MODx, PHP, web development

PhpThumbOf is a MODx Revolution add-on that is based on the popular php script called phpThumb. It allows you to use the graphics libraries on an Apache server to make modifications to images on-the-fly.

This is an entry that is based on the presentation of phpThumbOf that I gave at the June MODx Houston Meetup, which demonstrates some of the awesome things we can do to manipulate images using phpThumbOf in MODx Revolution.

I’m not going to go through the process of how to download and install phpThumbOf from the MODx repository. I’ll assume that you’ve already downloaded and installed the add-on. There are no other add-ons that need to be installed to get this working.

These examples are created using MODx 2.1.0 and phpThumbOf 1.2.1-pl.

Note: there is also a MODx Evolution version of this add-on called phpThumb.

As of this writing, the official MODx documentation for phpThumbOf is pretty scarce. Initially, I thought you could only use the &zc= (zoom-crop) option when inserting an image because that’s all that’s mentioned in the add-on’s documentation. Then, I just randomly tried some of the other phpThumb options and they worked!

The Anatomy of a phpThumbOf Call— As an Output Filter

A MODx Output Filter allows you to pass the value of an element through any of a set of filters to modify it before it’s loaded into the page. The syntax looks like this

[[element:modifier=`value`]]

The first, and most common, way that you can use phpThumbOf is by using it as an Output Filter, attaching it to an image-based Template Variable in MODx.

Just to be thorough, I’m going to walk through the creation of an image-based template variable.

First, you’ll create a new template variable and name it whatever you want. Take the following, for example:

Fields for creating a new Template Variable

Then choose ‘Image’ as the input type under Input Options.

Select 'Image' as the input option

We’ll select the following image as the source of our Template Variable:

All we have to do is set this TV output as the src of our image. The code to call this Template Variable looks like this:

<img src="[[*tvImage]]" />

As we mentioned at the outset, an output filter modifies the element before it’s printed to the page. So we attach the phpThumbOf Output Filter to our previous TV call, like so.

[[*tvImage:phpthumbof=`w=120&h=120`]]

Note: If this is being called inside a TPL file or Chunk, then the asterisk becomes a plus: [[+tvImage:phpthumbof=`w=120&h=120`]]

The result is a newly-generated image, based on the image you choose for the ‘tvImage’ template variable that is resized to 120px by 120px. But if you notice, it has added a white background to keep our image’s size ratio stays intact.

Image resized to 120px by 120px

If you don’t want it to force a background, simply leave off either the width or height. Here’s what happens if we only specify a width:

[[+tvImage:phpthumbof=`w=120`]]

It resizes to the specified width, and just lets the height fall to whatever proportionally matches this width.

120 Pixels, Width Only. Height automatically calculated.

Just so you can see that the resizing possibilities are extremely flexible, here is another example with a width of 270px defined. You can even output an image that’s larger than its source image. (Not that it would be a good idea).

[[*tvImage:phpthumbof=`w=270`]]

Cropping the Image to Exact Dimensions

If we want to crop it and make it exactly 120px by 120px version of our image, we’d add the zoom-crop option &zc=1.

[[*tvImage:phpthumbof=`w=120&h=120&zc=1`]]

Now, we have a cropped version of the same image with the exact dimensions we specified.

Note: As of this version (phpThumbOf 1.2.1-pl) crop gravity does not work. So, Changing the &zc= value to ‘C’, ‘T’, ‘B’, ‘L’, ‘R’, ‘TL’, ‘TR’, ‘BL’, ‘BR’ will not change the (top, bottom, left, right, etc.) area of the picture that the crop will be anchored to. It will always be center-weighted.

PhpThumb’s Filters— Where the Fun Really Begins

Now that you know how to manipulate the size of the image, we’ll get into what I consider to be the real power of phpThumb: filters. I’m just going to throw out several demos of the filters available in phpThumb. Notice that we’re simply adding new filters to the end of previous phpThumb options. Order DOES matter. Filters are applied from left to right.

Blur

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=blur|10`]]

120px by 120px with a blur value of 10

Grayscale

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=gray`]]

120px by 120px in grayscale

Rounded Corners

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=ric|20|20`]]

120px by 120px with rounded corners

Notice how the filter is adding the white background into the non-image areas where the rounded corners are? We can get rid of that by switching the image type from JPG, to PNG.

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&f=png&fltr[]=ric|20|20`]]

120px by 120px, rounded as transparent PNG

Borders

We all want to add borders to images. You can do it with CSS, of course. But there are times when you might want to do it within the graphic itself. I don’t like going into Photoshop for simple stuff like this. It’s overkill. So, take a look at once such instance where I’d use phpThumb instead of CSS:

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&f=png&fltr[]=bord|5|0|0|FFFFFF&fltr[]=rot|-15|E4F6FE`]]

PNG output, border 5px with no curves, set to white. Rotated -15° with a matte color of #E4F6FE that matches the background

Rotate Graphic

Rotation requires a little explanation. You must specify a background color for the non-graphic area in the corners. In this example, we use #006699. The rotation is -45°

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=rot|-45|006699`]]

120px by 120px, rotated -45 degrees

If you want to reduce the JPG ugliness, you can increase the JPG quality (1-100):

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=rot|-45|006699&q=100`]]

120px by 120px, rotated -45° with JPEG quality 100

If you want to have a transparent background, just change the output to PNG like we did before:

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=rot|-45|&f=png`]]

120px by 120px, rotated -45° with transparent png

Color Overlay

The colorize filter allows you to overlay any hex color over an image. The first value is the percentage, the second is the hex value.

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=clr|35|990033`]]

120px by 120px with 35% color overlay of #990033

If you want a duotone effect, just precede the overlay filter with a grayscale filter to remove the image’s color first.

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=gray&fltr[]=clr|35|990033`]]

120px by 120px with 35% color overlay of #990033 atop a grayscale image, which gives us our duotone effect

Basic Text Watermark

You can do text and image watermarks as well, using phpThumb. With text watermarks, you can define the size, placement, opacity and even the TTF font you want it to be rendered with.

There are a lot of variables to set. Check original documentation to see all options.

Here’s a simple text watermark using a default server font:

[[*tvImage:phpthumbof=`w=120&h=120&zc=1&fltr[]=gray&fltr[]=wmt|Belafonte Code|3|T|FFFFFF||100|20|0||0|`]]

120px by 120px with basic text watermark, aligned-top, offset with 20% margin

Direct Image Manipulation

Output Filters are excellent, but what if you just want to modify a single image without creating a Template Variable for it? To do that, we call phpThumbOf as a snippet and then pass the image url and options into it:

<img src="[[phpthumbof? &input=`/assets/images/hot-air-balloons.jpg` &options=`&w=120&h=120&zc=1&fltr[]=gray`]]" />

You can chain the filters at the end of the options query string all the same.

Note: If you want to see all the rest of the MANY options available, check the phpThumb demos page.

Note: I have not gotten drop shadows with fades to work.

You’re probably thinking of all the amazing things you can do with this so you don’t have to go into Photoshop for simple graphic tweaks. It also gives you the power to let users and content editors add graphics to pages and always know that they will be formatted according to your design specification.

Feel free to leave some of your awesome and clever uses of phpThumb in the comments.

Evo version of this demo coming soon.

View Comments (6)