Last updated 23 March 2008. Created on 23 March 2008.
Edited by jpoesen. Log in to edit this page.

ImageAPI is an image manipulation API that was extracted from imagecache 1.x when version 2.x was built. Of course, imagecache 2.x now depends on it.

About imagecache

Imagecache is a module that generates resized and/or cropped versions of images. You define different "presets", indicate what actions (resize, crop, desaturate, ...) need to be performed in what order, and all these image versions will be available alongside the original image you uploaded. In addition, it does caching and some other intelligent stuff.

Basically, imagecache is what you need if you want to generate thumbnails (think user profiles and image galleries), and different size and/or quality versions (like flickr).


ImageAPI supports multiple image manipulation libraries. GD is fully supported and ImageMagick support is added, but still experimental at the time of writing. The API allows easy image manipulation without the need of installing the entire imagecache module.

API Quick Reference

  imageapi_image_scale_and_crop($image, $width, $height) 
  imageapi_image_scale($image, $width, $height, $upscale = FALSE) 
  imageapi_image_resize($image, $width, $height) 
  imageapi_image_rotate($image, $degrees, $bgcolor = 0x000000) 
  imageapi_image_crop($image, $x, $y, $width, $height) 
  imageapi_image_open($file, $toolkit = FALSE) 
  imageapi_image_close($image, $destination) 

  $image is an image object returned from imageapi_image_open();

An example

Let's illustrate with a small snippet that implements hook_nodeapi.

Just stick this code in myfoo.module, provide a info fileand enable the module.

The function will check if the node is of type 'foo' and make sure the code is only executed when the operation being performed on the node is 'submit' (so each time a node is inserted/updated + passed validation). A final check is made to make sure one or more files are attached.

Each image is opened, a manipulation is performed, and the resulting image is saved. Note that, in this case, a copy of the original image is saved.

 * implementation of hook_nodeapi()
function myfoo_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
  // check node type
  if ($node->type == "foo"){

    switch ($op) {

      // check operation being performed
      case 'submit':

        // check if the field in question is present 
        // and that it's an array
        if (isset ($node->field_foo_image) 
          && is_array ($node->field_foo_image)){

          foreach ($node->field_foo_image as $img){
            if ($img["filepath"] != ""){
              $image = imageapi_image_open ($img["filepath"]);
              imageapi_image_scale_and_crop ($image, 80, 90); 
              imageapi_image_close ($image, $img["filepath"]);			

Some code improvements could be added and some additional logic should be added to check if an image has already been resized, but that's beside the point. This is just an example to demonstrate how to get started with custom image manipulation in just a few lines of code.

Looking for support? Visit the forums, or join #drupal-support in IRC.


W.M.’s picture

I have a question regarding "imageapi_image_scale($image, $width, $height, $upscale = FALSE)".

How to configure settings for width and height if I need to scale only by width. I tried this but failed:

imageapi_image_scale($image, '800', '', $upscale = FALSE);