- Patch #148346 by Steef and drewish: split image.inc into image.inc and image.gd.inc and improved the documentation.

2 files changed, 298 insertions, 199 deletions

diff --git a/includes/image.gd.inc b/includes/image.gd.inc
new file mode 100644
index 000000000..4e3612fd2
--- /dev/null
+++ b/includes/image.gd.inc
@@ -0,0 +1,191 @@
+<?php
+// $id: $
+
+/**
+ * @file
+ * GD2 toolkit for image manipulation within Drupal.
+ */
+
+/**
+ * @ingroup image
+ * @{
+ */
+
+/**
+ * Retrieve information about the toolkit.
+ */
+function image_gd_info() {
+  return array('name' => 'gd', 'title' => t('GD2 image manipulation toolkit'));
+}
+
+/**
+ * Retrieve settings for the GD2 toolkit.
+ */
+function image_gd_settings() {
+  if (image_gd_check_settings()) {
+    $form = array();
+    $form['status'] = array(
+      '#value' => t('The GD toolkit is installed and working properly.')
+    );
+
+    $form['image_jpeg_quality'] = array(
+      '#type' => 'textfield',
+      '#title' => t('JPEG quality'),
+      '#description' => t('Define the image quality for JPEG manipulations. Ranges from 0 to 100. Higher values mean better image quality but bigger files.'),
+      '#size' => 10,
+      '#maxlength' => 3,
+      '#default_value' => variable_get('image_jpeg_quality', 75),
+      '#field_suffix' => t('%'),
+    );
+
+    return $form;
+  }
+  else {
+    form_set_error('image_toolkit', t('The GD image toolkit requires that the GD module for PHP be installed and configured properly. For more information see <a href="@url">PHP\'s image documentation</a>.', array('@url' => 'http://php.net/image')));
+    return FALSE;
+  }
+}
+
+/**
+ * Verify GD2 settings (that the right version is actually installed).
+ *
+ * @return
+ *   A boolean indicating if the GD toolkit is avaiable on this machine.
+ */
+function image_gd_check_settings() {
+  if ($check = get_extension_funcs('gd')) {
+    if (in_array('imagegd2', $check)) {
+      // GD2 support is available.
+      return TRUE;
+    }
+  }
+  return FALSE;
+}
+
+/**
+ * Scale an image to the specified size using GD.
+ */
+function image_gd_resize($source, $destination, $width, $height) {
+  if (!file_exists($source)) {
+    return FALSE;
+  }
+
+  $info = image_get_info($source);
+  if (!$info) {
+    return FALSE;
+  }
+
+  $im = image_gd_open($source, $info['extension']);
+  if (!$im) {
+    return FALSE;
+  }
+
+  $res = imageCreateTrueColor($width, $height);
+  if ($info['extension'] == 'png') {
+    $transparency = imagecolorallocatealpha($res, 0, 0, 0, 127);
+    imagealphablending($res, FALSE);
+    imagefilledrectangle($res, 0, 0, $width, $height, $transparency);
+    imagealphablending($res, TRUE);
+    imagesavealpha($res, TRUE);
+  }
+  imageCopyResampled($res, $im, 0, 0, 0, 0, $width, $height, $info['width'], $info['height']);
+  $result = image_gd_close($res, $destination, $info['extension']);
+
+  imageDestroy($res);
+  imageDestroy($im);
+
+  return $result;
+}
+
+/**
+ * Rotate an image the given number of degrees.
+ */
+function image_gd_rotate($source, $destination, $degrees, $background = 0x000000) {
+  if (!function_exists('imageRotate')) {
+    return FALSE;
+  }
+
+  $info = image_get_info($source);
+  if (!$info) {
+    return FALSE;
+  }
+
+  $im = image_gd_open($source, $info['extension']);
+  if (!$im) {
+    return FALSE;
+  }
+
+  $res = imageRotate($im, $degrees, $background);
+  $result = image_gd_close($res, $destination, $info['extension']);
+
+  return $result;
+}
+
+/**
+ * Crop an image using the GD toolkit.
+ */
+function image_gd_crop($source, $destination, $x, $y, $width, $height) {
+  $info = image_get_info($source);
+  if (!$info) {
+    return FALSE;
+  }
+
+  $im = image_gd_open($source, $info['extension']);
+  $res = imageCreateTrueColor($width, $height);
+  imageCopy($res, $im, 0, 0, $x, $y, $width, $height);
+  $result = image_gd_close($res, $destination, $info['extension']);
+
+  imageDestroy($res);
+  imageDestroy($im);
+
+  return $result;
+}
+
+/**
+ * GD helper function to create an image resource from a file.
+ *
+ * @param $file
+ *   A string file path where the iamge should be saved.
+ * @param $extension
+ *   A string containing one of the following extensions: gif, jpg, jpeg, png.
+ * @return
+ *   An image resource, or FALSE on error.
+ */
+function image_gd_open($file, $extension) {
+  $extension = str_replace('jpg', 'jpeg', $extension);
+  $open_func = 'imageCreateFrom'. $extension;
+  if (!function_exists($open_func)) {
+    return FALSE;
+  }
+  return $open_func($file);
+}
+
+/**
+ * GD helper to write an image resource to a destination file.
+ *
+ * @param $res
+ *   An image resource created with image_gd_open().
+ * @param $destination
+ *   A string file path where the iamge should be saved.
+ * @param $extension
+ *   A string containing one of the following extensions: gif, jpg, jpeg, png.
+ * @return
+ *   Boolean indicating success.
+ */
+function image_gd_close($res, $destination, $extension) {
+  $extension = str_replace('jpg', 'jpeg', $extension);
+  $close_func = 'image'. $extension;
+  if (!function_exists($close_func)) {
+    return FALSE;
+  }
+  if ($extension == 'jpeg') {
+    return $close_func($res, $destination, variable_get('image_jpeg_quality', 75));
+  }
+  else {
+    return $close_func($res, $destination);
+  }
+}
+
+/**
+ * @} End of "ingroup image".
+ */
diff --git a/includes/image.inc b/includes/image.inc
index 38bd67338..8c66557d9 100644
--- a/includes/image.inc
+++ b/includes/image.inc
@@ -2,9 +2,35 @@
 // $Id$
 
 /**
+ * @file
+ * API for manipulating images.
+ */
+
+/**
+ * @defgroup image Image toolkits
+ * @{
+ * Drupal's image toolkits provide an abstraction layer for common image file
+ * manipulations like scaling, cropping, and rotating. The abstraction frees
+ * module authors from the need to support multiple image libraries, and it
+ * allows site administrators to choose the library that's best for them.
+ *
+ * PHP includes the GD library by default so a GD toolkit is installed with
+ * Drupal. Other toolkits like ImageMagic are available from contrib modules.
+ * GD works well for small images, but using it with larger files may cause PHP
+ * to run out of memory. In contrast the ImageMagick library does not suffer
+ * from this problem, but it requires the ISP to have installed additional
+ * software.
+ *
+ * Image toolkits are installed by copying the image.$name.inc file into
+ * Drupal's includes directory. The toolkit must then be enabled using the
+ * form at ?q=admin/settings/image-toolkit.
+ */
+
+/**
  * Return a list of available toolkits.
  *
- * @return An array of toolkit name => descriptive title.
+ * @return
+ *   An array of toolkit name => descriptive title.
  */
 function image_get_available_toolkits() {
   $toolkits = file_scan_directory('includes', 'image\..*\.inc$');
@@ -18,21 +44,23 @@ function image_get_available_toolkits() {
       $output[$info['name']] = $info['title'];
     }
   }
-  $output['gd'] = t('Built-in GD2 toolkit');
+
   return $output;
 }
 
 /**
  * Retrieve the name of the currently used toolkit.
  *
- * @return String containing the name of the toolkit.
+ * @return
+ *   String containing the name of the selected toolkit, or FALSE on error.
  */
 function image_get_toolkit() {
   static $toolkit;
+
   if (!$toolkit) {
     $toolkit = variable_get('image_toolkit', 'gd');
     $toolkit_file = './includes/image.'. $toolkit .'.inc';
-    if ($toolkit != 'gd' && file_exists($toolkit_file)) {
+    if (isset($toolkit) && file_exists($toolkit_file)) {
       include_once $toolkit_file;
     }
     elseif (!image_gd_check_settings()) {
@@ -46,10 +74,12 @@ function image_get_toolkit() {
 /**
  * Invokes the given method using the currently selected toolkit.
  *
- * @param $method A string containing the method to invoke.
- * @param $params An optional array of parameters to pass to the toolkit method.
- *
- * @return Mixed values (typically Boolean for successful operation).
+ * @param $method
+ *   A string containing the method to invoke.
+ * @param $params
+ *   An optional array of parameters to pass to the toolkit method.
+ * @return
+ *   Mixed values (typically boolean indicating successful operation).
  */
 function image_toolkit_invoke($method, $params = array()) {
   if ($toolkit = image_get_toolkit()) {
@@ -62,23 +92,22 @@ function image_toolkit_invoke($method, $params = array()) {
       return FALSE;
     }
   }
-  else {
-    if ($method == 'settings') {
-      return image_gd_settings();
-    }
-  }
 }
 
 
 /**
  * Get details about an image.
  *
- * @return array containing information about the image
- *      'width': image's width in pixels
- *      'height': image's height in pixels
- *      'extension': commonly used extension for the image
- *      'mime_type': image's MIME type ('image/jpeg', 'image/gif', etc.)
- *      'file_size': image's physical size (in bytes)
+ * Drupal only supports GIF, JPG and PNG file formats.
+ *
+ * @return
+ *   FALSE, if the file could not be found or is not an image. Otherwise, a
+ *   keyed array containing information about the image:
+ *    'width'     - Width in pixels.
+ *    'height'    - Height in pixels.
+ *    'extension' - Commonly used file extension for the image.
+ *    'mime_type' - MIME type ('image/jpeg', 'image/gif', 'image/png').
+ *    'file_size' - File size in bytes.
  */
 function image_get_info($file) {
   if (!is_file($file)) {
@@ -110,12 +139,16 @@ function image_get_info($file) {
  *
  * The resulting image always has the exact target dimensions.
  *
- * @param $source         The file path of the source image
- * @param $destination    The file path of the destination image
- * @param $width          The target width
- * @param $height         The target height
- *
- * @return TRUE or FALSE, based on success
+ * @param $source
+ *   The file path of the source image.
+ * @param $destination
+ *   The file path of the destination image.
+ * @param $width
+ *   The target width, in pixels.
+ * @param $height
+ *   The target height, in pixels.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
 function image_scale_and_crop($source, $destination, $width, $height) {
   $info = image_get_info($source);
@@ -136,12 +169,16 @@ function image_scale_and_crop($source, $destination, $width, $height) {
  *
  * The resulting image can be smaller for one or both target dimensions.
  *
- * @param $source         The file path of the source image
- * @param $destination    The file path of the destination image
- * @param $width          The target width
- * @param $height         The target height
- *
- * @return True or FALSE, based on success
+ * @param $source
+ *   The file path of the source image.
+ * @param $destination
+ *   The file path of the destination image.
+ * @param $width
+ *   The target width, in pixels.
+ * @param $height
+ *   The target height, in pixels.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
 function image_scale($source, $destination, $width, $height) {
   $info = image_get_info($source);
@@ -167,10 +204,16 @@ function image_scale($source, $destination, $width, $height) {
 /**
  * Resize an image to the given dimensions (ignoring aspect ratio).
  *
- * @param $source        The filepath of the source image.
- * @param $destination   The file path of the destination image.
- * @param $width         The target width.
- * @param $height        The target height.
+ * @param $source
+ *   The file path of the source image.
+ * @param $destination
+ *   The file path of the destination image.
+ * @param $width
+ *   The target width, in pixels.
+ * @param $height
+ *   The target height, in pixels.
+  * @return
+ *   TRUE or FALSE, based on success.
  */
 function image_resize($source, $destination, $width, $height) {
   return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
@@ -179,180 +222,45 @@ function image_resize($source, $destination, $width, $height) {
 /**
  * Rotate an image by the given number of degrees.
  *
- * @param $source  The filepath of the source image
- * @param $destination    The file path of the destination image
- * @param $degrees The number of (clockwise) degrees to rotate the image
+ * @param $source
+ *   The file path of the source image.
+ * @param $destination
+ *   The file path of the destination image.
+ * @param $degrees
+ *   The number of (clockwise) degrees to rotate the image.
+ * @param $background
+ *   An hexidecimal integer specifying the background color to use for the
+ *   uncovered area of the image after the rotation. E.g. 0x000000 for black,
+ *   0xff00ff for magenta, and 0xffffff for white.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
-function image_rotate($source, $destination, $degrees) {
-  return image_toolkit_invoke('rotate', array($source, $destination, $degrees));
+function image_rotate($source, $destination, $degrees, $background = 0x000000) {
+  return image_toolkit_invoke('rotate', array($source, $destination, $degrees, $background));
 }
 
 /**
  * Crop an image to the rectangle specified by the given rectangle.
  *
- * @param $source        The filepath of the source image
- * @param $destination   The file path of the destination image
- * @param $x             The top left co-ordinate of the crop area (x axis value)
- * @param $y             The top left co-ordinate of the crop area (y axis value)
- * @param $width         The target width
- * @param $height        The target height
+ * @param $source
+ *   The file path of the source image.
+ * @param $destination
+ *   The file path of the destination image.
+ * @param $x
+ *   The top left co-ordinate, in pixels, of the crop area (x axis value).
+ * @param $y
+ *   The top left co-ordinate, in pixels, of the crop area (y axis value).
+ * @param $width
+ *   The target width, in pixels.
+ * @param $height
+ *   The target height, in pixels.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
 function image_crop($source, $destination, $x, $y, $width, $height) {
   return image_toolkit_invoke('crop', array($source, $destination, $x, $y, $width, $height));
 }
 
 /**
- * GD2 toolkit functions
- * With the minimal requirements of PHP 4.3 for Drupal, we use the built-in version of GD.
- */
-
-/**
- * Retrieve settings for the GD2 toolkit.
- */
-function image_gd_settings() {
-  if (image_gd_check_settings()) {
-    $form = array();
-    $form['status'] = array('#value' => t('The built-in GD2 toolkit is installed and working properly.'));
-
-    $form['image_jpeg_quality'] = array(
-      '#type' => 'textfield',
-      '#title' => t('JPEG quality'),
-      '#description' => t('Define the image quality for JPEG manipulations. Ranges from 0 to 100. Higher values mean better image quality but bigger files.'),
-      '#size' => 10,
-      '#maxlength' => 3,
-      '#default_value' => variable_get('image_jpeg_quality', 75),
-      '#field_suffix' => t('%'),
-    );
-
-    return $form;
-  }
-  else {
-    form_set_error('image_toolkit', t('The built-in GD image toolkit requires that the GD module for PHP be installed and configured properly. For more information see <a href="@url">PHP\'s image documentation</a>.', array('@url' => 'http://php.net/image')));
-    return FALSE;
-  }
-}
-
-/**
- * Verify GD2 settings (that the right version is actually installed).
- *
- * @return boolean
- */
-function image_gd_check_settings() {
-  if ($check = get_extension_funcs('gd')) {
-    if (in_array('imagegd2', $check)) {
-      // GD2 support is available.
-      return TRUE;
-    }
-  }
-  return FALSE;
-}
-
-/**
- * Scale an image to the specified size using GD.
- */
-function image_gd_resize($source, $destination, $width, $height) {
-  if (!file_exists($source)) {
-    return FALSE;
-  }
-
-  $info = image_get_info($source);
-  if (!$info) {
-    return FALSE;
-  }
-
-  $im = image_gd_open($source, $info['extension']);
-  if (!$im) {
-    return FALSE;
-  }
-
-  $res = imageCreateTrueColor($width, $height);
-  if ($info['extension'] == 'png') {
-    $transparency = imagecolorallocatealpha($res, 0, 0, 0, 127);
-    imagealphablending($res, FALSE);
-    imagefilledrectangle($res, 0, 0, $width, $height, $transparency);
-    imagealphablending($res, TRUE);
-    imagesavealpha($res, TRUE);
-  }
-  imageCopyResampled($res, $im, 0, 0, 0, 0, $width, $height, $info['width'], $info['height']);
-  $result = image_gd_close($res, $destination, $info['extension']);
-
-  imageDestroy($res);
-  imageDestroy($im);
-
-  return $result;
-}
-
-/**
- * Rotate an image the given number of degrees.
- */
-function image_gd_rotate($source, $destination, $degrees, $bg_color = 0) {
-  if (!function_exists('imageRotate')) {
-    return FALSE;
-  }
-
-  $info = image_get_info($source);
-  if (!$info) {
-    return FALSE;
-  }
-
-  $im = image_gd_open($source, $info['extension']);
-  if (!$im) {
-    return FALSE;
-  }
-
-  $res = imageRotate($im, $degrees, $bg_color);
-  $result = image_gd_close($res, $destination, $info['extension']);
-
-  return $result;
-}
-
-/**
- * Crop an image using the GD toolkit.
+ * @} End of "defgroup image".
  */
-function image_gd_crop($source, $destination, $x, $y, $width, $height) {
-  $info = image_get_info($source);
-  if (!$info) {
-    return FALSE;
-  }
-
-  $im = image_gd_open($source, $info['extension']);
-  $res = imageCreateTrueColor($width, $height);
-  imageCopy($res, $im, 0, 0, $x, $y, $width, $height);
-  $result = image_gd_close($res, $destination, $info['extension']);
-
-  imageDestroy($res);
-  imageDestroy($im);
-
-  return $result;
-}
-
-/**
- * GD helper function to create an image resource from a file.
- */
-function image_gd_open($file, $extension) {
-  $extension = str_replace('jpg', 'jpeg', $extension);
-  $open_func = 'imageCreateFrom'. $extension;
-  if (!function_exists($open_func)) {
-    return FALSE;
-  }
-  return $open_func($file);
-}
-
-/**
- * GD helper to write an image resource to a destination file.
- */
-function image_gd_close($res, $destination, $extension) {
-  $extension = str_replace('jpg', 'jpeg', $extension);
-  $close_func = 'image'. $extension;
-  if (!function_exists($close_func)) {
-    return FALSE;
-  }
-  if ($extension == 'jpeg') {
-    return $close_func($res, $destination, variable_get('image_jpeg_quality', 75));
-  }
-  else {
-    return $close_func($res, $destination);
-  }
-}
-
-