Attache-ImageSizer

Summary: Resize and manipulate uploaded images
Version: 2017-09-05
Prerequisites: PmWiki 2.2.3 or later and ImageMagick
Status: beta
Maintainer: Eemeli Aro
License: ISC (also available with GPL2 license)
Users: (View? / Edit?)

Description

ImageSizer lets you define and use different formats and sizes in which to serve images uploaded to PmWiki.

With the default settings, if you upload an image duck.jpg, you can automatically use Attach:duck--thumb.jpg as a max 50px wide and tall thumbnail. Attach:duck.jpg provides an image that fits in a 500×500px box and Attach:duck--orig.jpg serves the original full-resolution image. The various images are generated on first access and cached until the original image is updated.

Fake example

Attach:duck--thumb.jpg

Attach:duck.jpg

The above thumbnail is actually a separate attachment uploaded to pmwiki.org, as the recipe isn't enabled here. It was, however, generated by ImageSizer on a different server. In actual use, you wouldn't see duck--thumb.jpg in an (:attachlist:) and it would disappear if you removed the original duck.jpg.

Requirements

You'll need to have ImageMagick installed on the server and make sure that its convert command is executable by your webserver user.

As the recipe works on file access, you'll need to have $EnableDirectDownload disabled or use Apache RewriteRules to redirect "direct download" links to PmWiki (instructions). If that's not possible, you should take a look at AutoThumber, which can generate thumbnails and other image versions when you upload a file.

To install:

include_once("$FarmD/cookbook/attache-imagesizer.php");

Usage

Upload an image file (JPEG, PNG or GIF by default; defined by $ImgExtPattern) and link to it. Use Attach:duck.jpg to show the image inline, or make a thumbnail link to the original: [[Attach:duck--orig.jpg|Attach:duck--thumb.jpg]].

Configuration

The $ImgSizer global array may be used to control the recipe. You may set values in the array at any point in your configuration.

KeyDefault valueExplanation
'cache-dir'$WorkDirThe directory where converted files are cached
'convert-cmd''convert'The command to use for ImageMagick
'default-opt'
array(
  'fmt' => 'default',
  'w' => '500',
  'h' => '500')
Default values for parameters
'convert-fmt'
array(
  'default' => "-resize '%wx%h>'",
  'thumb' => "-resize '50x50>'",
  'orig' => '')
Conversion options for different formats
'separator''--'String separating image formatting commands
'HandleDownloadFunction''HandleDownload'Function for downloading non-image files
'LinkUploadFunction''LinkUpload'Function for generating a link to non-image files

For example, to disable the resizing of Attach:duck.jpg and to generate a slightly bigger sepia-toned thumbnail, you could use:

$ImgSizer['convert-fmt'] = array('default' => '', 'thumb' => "-resize '80x80>' -sepia-tone 80%");

Note that the 'quotes' are required around the resize parameter due to the > character.

Notes

ImageSizer is a part of Cookbook.Attache, but may also be used as a standalone recipe.

You may allow image parameters to be set by the requested file name. For example, by default Attach:duck--w150.jpg will serve an image that's at most 150 pixels wide (and 500 pixels tall, as per the defaults). These parameters need to use a single lower-case letter (a-z) as an identifier and may either have a numeric value or one composed of word characters (a-z, A-Z, 0-9, _). Numeric values may include a decimal dot, encoded as an underscore (eg. duck--x0_75.jpg). Word values need to be separated from the identifier by an underscore (eg. duck--c_Grayscale.jpg). Use a % symbol in the convert command to include a parameter value (eg. "-resize '%wx%h>'").

The recipe doesn't (yet) provide an automated method of clearing the cache. The cached converted images are kept in $WorkDir, with filenames of the form img_[hash],cache where [hash] is an MD5 hash of the conversion command. These files may safely be deleted, as any that are in use will be re-generated on their next access.

The recipe's intent is the same as that of AutoThumber, but the implementation ended up completely different: ImageSizer works on file access, AutoThumber on file upload. Due to these differences I've published these as separate recipes.

Release notes

  • 2017-09-05 — Updated for PHP 5.5 compatibility.
  • 2010-05-04Δ — first public release

See also

Contributors

Comments

See discussion at Attache-ImageSizer-Talk

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.