[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @file
   5   * API for manipulating images.
   6   */
   7  
   8  /**
   9   * @defgroup image Image toolkits
  10   * @{
  11   * Drupal's image toolkits provide an abstraction layer for common image file
  12   * manipulations like scaling, cropping, and rotating. The abstraction frees
  13   * module authors from the need to support multiple image libraries, and it
  14   * allows site administrators to choose the library that's best for them.
  15   *
  16   * PHP includes the GD library by default so a GD toolkit is installed with
  17   * Drupal. Other toolkits like ImageMagic are available from contrib modules.
  18   * GD works well for small images, but using it with larger files may cause PHP
  19   * to run out of memory. In contrast the ImageMagick library does not suffer
  20   * from this problem, but it requires the ISP to have installed additional
  21   * software.
  22   *
  23   * Image toolkits are installed by copying the image.ToolkitName.inc file into
  24   * Drupal's includes directory. The toolkit must then be enabled using the
  25   * admin/settings/image-toolkit form.
  26   *
  27   * Only one toolkit maybe selected at a time. If a module author wishes to call
  28   * a specific toolkit they can check that it is installed by calling
  29   * image_get_available_toolkits(), and then calling its functions directly.
  30   */
  31  
  32  /**
  33   * Return a list of available toolkits.
  34   *
  35   * @return
  36   *   An array of toolkit name => descriptive title.
  37   */
  38  function image_get_available_toolkits() {
  39    $toolkits = file_scan_directory('includes', 'image\..*\.inc$');
  40  
  41    $output = array();
  42    foreach ($toolkits as $file => $toolkit) {
  43      include_once "./$file";
  44      $function = str_replace('.', '_', $toolkit->name) .'_info';
  45      if (function_exists($function)) {
  46        $info = $function();
  47        $output[$info['name']] = $info['title'];
  48      }
  49    }
  50  
  51    return $output;
  52  }
  53  
  54  /**
  55   * Retrieve the name of the currently used toolkit.
  56   *
  57   * @return
  58   *   String containing the name of the selected toolkit, or FALSE on error.
  59   */
  60  function image_get_toolkit() {
  61    static $toolkit;
  62  
  63    if (!$toolkit) {
  64      $toolkit = variable_get('image_toolkit', 'gd');
  65      $toolkit_file = './includes/image.'. $toolkit .'.inc';
  66      if (isset($toolkit) && file_exists($toolkit_file)) {
  67        include_once $toolkit_file;
  68      }
  69      elseif (!image_gd_check_settings()) {
  70        $toolkit = FALSE;
  71      }
  72    }
  73  
  74    return $toolkit;
  75  }
  76  
  77  /**
  78   * Invokes the given method using the currently selected toolkit.
  79   *
  80   * @param $method
  81   *   A string containing the method to invoke.
  82   * @param $params
  83   *   An optional array of parameters to pass to the toolkit method.
  84   * @return
  85   *   Mixed values (typically Boolean indicating successful operation).
  86   */
  87  function image_toolkit_invoke($method, $params = array()) {
  88    if ($toolkit = image_get_toolkit()) {
  89      $function = 'image_'. $toolkit .'_'. $method;
  90      if (function_exists($function)) {
  91        return call_user_func_array($function, $params);
  92      }
  93      else {
  94        watchdog('php', 'The selected image handling toolkit %toolkit can not correctly process %function.', array('%toolkit' => $toolkit, '%function' => $function), WATCHDOG_ERROR);
  95        return FALSE;
  96      }
  97    }
  98  }
  99  
 100  
 101  /**
 102   * Get details about an image.
 103   *
 104   * Drupal only supports GIF, JPG and PNG file formats.
 105   *
 106   * @return
 107   *   FALSE, if the file could not be found or is not an image. Otherwise, a
 108   *   keyed array containing information about the image:
 109   *    'width'     - Width in pixels.
 110   *    'height'    - Height in pixels.
 111   *    'extension' - Commonly used file extension for the image.
 112   *    'mime_type' - MIME type ('image/jpeg', 'image/gif', 'image/png').
 113   *    'file_size' - File size in bytes.
 114   */
 115  function image_get_info($file) {
 116    // Proceed no further if this file doesn't exist. Some web servers (IIS) may
 117    // not pass is_file() for newly uploaded files, so we need two checks here.
 118    if (!is_file($file) && !is_uploaded_file($file)) {
 119      return FALSE;
 120    }
 121  
 122    $details = FALSE;
 123    $data = @getimagesize($file);
 124    $file_size = @filesize($file);
 125  
 126    if (isset($data) && is_array($data)) {
 127      $extensions = array('1' => 'gif', '2' => 'jpg', '3' => 'png');
 128      $extension = array_key_exists($data[2], $extensions) ?  $extensions[$data[2]] : '';
 129      $details = array('width'     => $data[0],
 130                       'height'    => $data[1],
 131                       'extension' => $extension,
 132                       'file_size' => $file_size,
 133                       'mime_type' => $data['mime']);
 134    }
 135  
 136    return $details;
 137  }
 138  
 139  /**
 140   * Scales an image to the exact width and height given. Achieves the
 141   * target aspect ratio by cropping the original image equally on both
 142   * sides, or equally on the top and bottom.  This function is, for
 143   * example, useful to create uniform sized avatars from larger images.
 144   *
 145   * The resulting image always has the exact target dimensions.
 146   *
 147   * @param $source
 148   *   The file path of the source image.
 149   * @param $destination
 150   *   The file path of the destination image.
 151   * @param $width
 152   *   The target width, in pixels.
 153   * @param $height
 154   *   The target height, in pixels.
 155   * @return
 156   *   TRUE or FALSE, based on success.
 157   */
 158  function image_scale_and_crop($source, $destination, $width, $height) {
 159    $info = image_get_info($source);
 160  
 161    $scale = max($width / $info['width'], $height / $info['height']);
 162    $x = round(($info['width'] * $scale - $width) / 2);
 163    $y = round(($info['height'] * $scale - $height) / 2);
 164  
 165    if (image_toolkit_invoke('resize', array($source, $destination, $info['width'] * $scale, $info['height'] * $scale))) {
 166      return image_toolkit_invoke('crop', array($destination, $destination, $x, $y, $width, $height));
 167    }
 168    return FALSE;
 169  }
 170  
 171  /**
 172   * Scales an image to the given width and height while maintaining aspect
 173   * ratio.
 174   *
 175   * The resulting image can be smaller for one or both target dimensions.
 176   *
 177   * @param $source
 178   *   The file path of the source image.
 179   * @param $destination
 180   *   The file path of the destination image.
 181   * @param $width
 182   *   The target width, in pixels.
 183   * @param $height
 184   *   The target height, in pixels.
 185   * @return
 186   *   TRUE or FALSE, based on success.
 187   */
 188  function image_scale($source, $destination, $width, $height) {
 189    $info = image_get_info($source);
 190  
 191    // Don't scale up.
 192    if ($width >= $info['width'] && $height >= $info['height']) {
 193      return FALSE;
 194    }
 195  
 196    $aspect = $info['height'] / $info['width'];
 197    if ($aspect < $height / $width) {
 198      $width = (int)min($width, $info['width']);
 199      $height = (int)round($width * $aspect);
 200    }
 201    else {
 202      $height = (int)min($height, $info['height']);
 203      $width = (int)round($height / $aspect);
 204    }
 205  
 206    return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
 207  }
 208  
 209  /**
 210   * Resize an image to the given dimensions (ignoring aspect ratio).
 211   *
 212   * @param $source
 213   *   The file path of the source image.
 214   * @param $destination
 215   *   The file path of the destination image.
 216   * @param $width
 217   *   The target width, in pixels.
 218   * @param $height
 219   *   The target height, in pixels.
 220    * @return
 221   *   TRUE or FALSE, based on success.
 222   */
 223  function image_resize($source, $destination, $width, $height) {
 224    return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
 225  }
 226  
 227  /**
 228   * Rotate an image by the given number of degrees.
 229   *
 230   * @param $source
 231   *   The file path of the source image.
 232   * @param $destination
 233   *   The file path of the destination image.
 234   * @param $degrees
 235   *   The number of (clockwise) degrees to rotate the image.
 236   * @param $background
 237   *   An hexidecimal integer specifying the background color to use for the
 238   *   uncovered area of the image after the rotation. E.g. 0x000000 for black,
 239   *   0xff00ff for magenta, and 0xffffff for white.
 240   * @return
 241   *   TRUE or FALSE, based on success.
 242   */
 243  function image_rotate($source, $destination, $degrees, $background = 0x000000) {
 244    return image_toolkit_invoke('rotate', array($source, $destination, $degrees, $background));
 245  }
 246  
 247  /**
 248   * Crop an image to the rectangle specified by the given rectangle.
 249   *
 250   * @param $source
 251   *   The file path of the source image.
 252   * @param $destination
 253   *   The file path of the destination image.
 254   * @param $x
 255   *   The top left co-ordinate, in pixels, of the crop area (x axis value).
 256   * @param $y
 257   *   The top left co-ordinate, in pixels, of the crop area (y axis value).
 258   * @param $width
 259   *   The target width, in pixels.
 260   * @param $height
 261   *   The target height, in pixels.
 262   * @return
 263   *   TRUE or FALSE, based on success.
 264   */
 265  function image_crop($source, $destination, $x, $y, $width, $height) {
 266    return image_toolkit_invoke('crop', array($source, $destination, $x, $y, $width, $height));
 267  }
 268  
 269  /**
 270   * @} End of "defgroup image".
 271   */