ImageToolkitInterface.php 4.26 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
<?php

/**
 * @file
 * Contains \Drupal\system\Plugin\ImageToolkitInterface.
 */

namespace Drupal\system\Plugin;

/**
 * Defines an interface for image toolkits.
 *
 * An image toolkit provides common image file manipulations like scaling,
 * cropping, and rotating.
 */
interface ImageToolkitInterface {

  /**
   * Retrieves toolkit's settings form.
   *
   * @see system_image_toolkit_settings()
   */
  function settingsForm();

  /**
   * Handles submissions for toolkit's settings form.
   *
   * @see system_image_toolkit_settings_submit()
   */
  function settingsFormSubmit($form, &$form_state);

  /**
   * Scales an image to the specified size.
   *
   * @param object $image
   *   An image object. The $image->resource, $image->info['width'], and
   *   $image->info['height'] values will be modified by this call.
   * @param int $width
   *   The new width of the resized image, in pixels.
   * @param int $height
   *   The new height of the resized image, in pixels.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_resize()
   */
  function resize($image, $width, $height);

  /**
   * Rotates an image the given number of degrees.
   *
   * @param object $image
   *   An image object. The $image->resource, $image->info['width'], and
   *   $image->info['height'] values will be modified by this call.
   * @param int $degrees
   *   The number of (clockwise) degrees to rotate the image.
   * @param string $background
   *   (optional) An hexadecimal 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. For images that
   *   support transparency, this will default to transparent. Otherwise it will
   *   be white.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_rotate()
   */
  function rotate($image, $degrees, $background = NULL);

  /**
   * Crops an image.
   *
   * @param object $image
   *   An image object. The $image->resource, $image->info['width'], and
   *   $image->info['height'] values will be modified by this call.
   * @param int $x
   *   The starting x offset at which to start the crop, in pixels.
   * @param int $y
   *   The starting y offset at which to start the crop, in pixels.
   * @param int $width
   *   The width of the cropped area, in pixels.
   * @param int $height
   *   The height of the cropped area, in pixels.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_crop()
   */
  function crop($image, $x, $y, $width, $height);

  /**
   * Converts an image resource to grayscale.
   *
   * Note that transparent GIFs loose transparency when desaturated.
   *
   * @param object $image
   *   An image object. The $image->resource value will be modified by this
   *   call.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_desaturate()
   */
  function desaturate($image);

  /**
   * Creates an image resource from a file.
   *
   * @param object $image
   *   An image object. The $image->resource value will populated by this call.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_load()
   */
  function load($image);

  /**
   * Writes an image resource to a destination file.
   *
   * @param object $image
   *   An image object.
   * @param string $destination
   *   A string file URI or path where the image should be saved.
   *
   * @return bool
   *   TRUE or FALSE, based on success.
   *
   * @see image_save()
   */
  function save($image, $destination);

  /**
   * Gets details about an image.
   *
   * @param object $image
   *   An image object.
   *
   * @return array
   *   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').
   *
   * @see image_get_info()
   */
  function getInfo($image);

  /**
   * Verifies Image Toolkit is set up correctly.
   *
   * @return bool
   *   True if the GD toolkit is available on this machine.
   */
  static function isAvailable();
}