Code coverage for /20080809/includes/image.inc

Line #Times calledCode
1
<?php
2
// $Id: image.inc,v 1.26 2008/07/08 01:08:15 dries Exp $
3
4
/**
5
 * @file
6
 * API for manipulating images.
7
 */
8
9
/**
10
 * @defgroup image Image toolkits
11
 * @{
12
 * Drupal's image toolkits provide an abstraction layer for common image
file
13
 * manipulations like scaling, cropping, and rotating. The abstraction
frees
14
 * module authors from the need to support multiple image libraries, and
it
15
 * allows site administrators to choose the library that's best for them.
16
 *
17
 * PHP includes the GD library by default so a GD toolkit is installed
with
18
 * Drupal. Other toolkits like ImageMagic are available from contrib
modules.
19
 * GD works well for small images, but using it with larger files may cause
PHP
20
 * to run out of memory. In contrast the ImageMagick library does not
suffer
21
 * from this problem, but it requires the ISP to have installed additional
22
 * software.
23
 *
24
 * Image toolkits are discovered based on the associated module's
25
 * hook_image_toolkits. Additionally the image toolkit include file
26
 * must be identified in the files array in the module.info file.  The
27
 * toolkit must then be enabled using the admin/settings/image-toolkit
28
 * form.
29
 *
30
 * Only one toolkit may be selected at a time. If a module author wishes to
call
31
 * a specific toolkit they can check that it is installed by calling
32
 * image_get_available_toolkits(), and then calling its functions
directly.
33
 */
34
35
/**
36
 * Return a list of available toolkits.
37
 *
38
 * @return
39
 *   An array of toolkit name => descriptive title.
40
 */
412027
function image_get_available_toolkits() {
42
  // hook_image_toolkits returns an array of toolkit names.
430
  $toolkits = module_invoke_all('image_toolkits');
44
450
  $output = array();
460
  foreach ($toolkits as $name) {
470
    $function = 'image_' . $name . '_info';
480
    if (drupal_function_exists($function)) {
490
      $info = $function();
500
      $output[$info['name']] = $info['title'];
510
    }
520
  }
530
  return $output;
540
}
55
56
/**
57
 * Retrieve the name of the currently used toolkit.
58
 *
59
 * @return
60
 *   String containing the name of the selected toolkit, or FALSE on
error.
61
 */
622027
function image_get_toolkit() {
632
  static $toolkit;
64
652
  if (!$toolkit) {
662
    $toolkit = variable_get('image_toolkit', 'gd');
672
    if (isset($toolkit) &&
682
      drupal_function_exists("image_" . $toolkit . "_resize")) {
692
    }
700
    elseif (!drupal_function_exists("image_gd_check_settings") ||
710
      !image_gd_check_settings()) {
720
      $toolkit = FALSE;
730
    }
742
  }
75
762
  return $toolkit;
770
}
78
79
/**
80
 * Invokes the given method using the currently selected toolkit.
81
 *
82
 * @param $method
83
 *   A string containing the method to invoke.
84
 * @param $params
85
 *   An optional array of parameters to pass to the toolkit method.
86
 * @return
87
 *   Mixed values (typically Boolean indicating successful operation).
88
 */
892027
function image_toolkit_invoke($method, $params = array()) {
901
  if ($toolkit = image_get_toolkit()) {
911
    $function = 'image_' . $toolkit . '_' . $method;
921
    if (drupal_function_exists($function)) {
931
      return call_user_func_array($function, $params);
940
    }
95
    else {
960
      watchdog('php', 'The selected image handling toolkit %toolkit can not
correctly process %function.', array('%toolkit' => $toolkit, '%function' =>
$function), WATCHDOG_ERROR);
970
      return FALSE;
98
    }
990
  }
1000
}
101
102
103
/**
104
 * Get details about an image.
105
 *
106
 * Drupal only supports GIF, JPG and PNG file formats.
107
 *
108
 * @return
109
 *   FALSE, if the file could not be found or is not an image. Otherwise,
a
110
 *   keyed array containing information about the image:
111
 *    'width'     - Width in pixels.
112
 *    'height'    - Height in pixels.
113
 *    'extension' - Commonly used file extension for the image.
114
 *    'mime_type' - MIME type ('image/jpeg', 'image/gif', 'image/png').
115
 *    'file_size' - File size in bytes.
116
 */
1172027
function image_get_info($file) {
11810
  if (!is_file($file)) {
1190
    return FALSE;
1200
  }
121
12210
  $details = FALSE;
12310
  $data = @getimagesize($file);
12410
  $file_size = @filesize($file);
125
12610
  if (isset($data) && is_array($data)) {
1274
    $extensions = array('1' => 'gif', '2' => 'jpg', '3' => 'png');
1284
    $extension = array_key_exists($data[2], $extensions) ? 
$extensions[$data[2]] : '';
1294
    $details = array('width'     => $data[0],
1304
                     'height'    => $data[1],
1314
                     'extension' => $extension,
1324
                     'file_size' => $file_size,
1334
                     'mime_type' => $data['mime']);
1344
  }
135
13610
  return $details;
1370
}
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
 */
1582027
function image_scale_and_crop($source, $destination, $width, $height) {
1590
  $info = image_get_info($source);
160
1610
  $scale = max($width / $info['width'], $height / $info['height']);
1620
  $x = round(($info['width'] * $scale - $width) / 2);
1630
  $y = round(($info['height'] * $scale - $height) / 2);
164
1650
  if (image_toolkit_invoke('resize', array($source, $destination,
$info['width'] * $scale, $info['height'] * $scale))) {
1660
    return image_toolkit_invoke('crop', array($destination, $destination,
$x, $y, $width, $height));
1670
  }
1680
  return FALSE;
1690
}
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
 */
1882027
function image_scale($source, $destination, $width, $height) {
1891
  $info = image_get_info($source);
190
191
  // Don't scale up.
1921
  if ($width >= $info['width'] && $height >= $info['height']) {
1930
    return FALSE;
1940
  }
195
1961
  $aspect = $info['height'] / $info['width'];
1971
  if ($aspect < $height / $width) {
1980
    $width = (int)min($width, $info['width']);
1990
    $height = (int)round($width * $aspect);
2000
  }
201
  else {
2021
    $height = (int)min($height, $info['height']);
2031
    $width = (int)round($height / $aspect);
204
  }
205
2061
  return image_toolkit_invoke('resize', array($source, $destination,
$width, $height));
2070
}
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
 */
2232027
function image_resize($source, $destination, $width, $height) {
2240
  return image_toolkit_invoke('resize', array($source, $destination,
$width, $height));
2250
}
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
 */
2432027
function image_rotate($source, $destination, $degrees, $background =
0x000000) {
2440
  return image_toolkit_invoke('rotate', array($source, $destination,
$degrees, $background));
2450
}
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
 */
2652027
function image_crop($source, $destination, $x, $y, $width, $height) {
2660
  return image_toolkit_invoke('crop', array($source, $destination, $x, $y,
$width, $height));
2670
}
268
269
/**
270
 * @} End of "defgroup image".
271
 */
2722027