aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Image/ImageInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Image;
   4
   5 /**
   6  * Provides an interface for image objects.
   7  */
   8 interface ImageInterface {
   9
  10   /**
  11    * Checks if the image is valid.
  12    *
  13    * @return bool
  14    *   TRUE if the image object contains a valid image, FALSE otherwise.
  15    */
  16   public function isValid();
  17
  18   /**
  19    * Returns the height of the image.
  20    *
  21    * @return int|null
  22    *   The height of the image, or NULL if the image is invalid.
  23    */
  24   public function getHeight();
  25
  26   /**
  27    * Returns the width of the image.
  28    *
  29    * @return int|null
  30    *   The width of the image, or NULL if the image is invalid.
  31    */
  32   public function getWidth();
  33
  34   /**
  35    * Returns the size of the image file.
  36    *
  37    * @return int|null
  38    *   The size of the file in bytes, or NULL if the image is invalid.
  39    */
  40   public function getFileSize();
  41
  42   /**
  43    * Returns the MIME type of the image file.
  44    *
  45    * @return string
  46    *   The MIME type of the image file, or an empty string if the image is
  47    *   invalid.
  48    */
  49   public function getMimeType();
  50
  51   /**
  52    * Retrieves the source path of the image file.
  53    *
  54    * @return string
  55    *   The source path of the image file. An empty string if the source is
  56    *   not set.
  57    */
  58   public function getSource();
  59
  60   /**
  61    * Returns the image toolkit used for this image file.
  62    *
  63    * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
  64    *   The image toolkit.
  65    */
  66   public function getToolkit();
  67
  68   /**
  69    * Returns the ID of the image toolkit used for this image file.
  70    *
  71    * @return string
  72    *   The ID of the image toolkit.
  73    */
  74   public function getToolkitId();
  75
  76   /**
  77    * Applies a toolkit operation to the image.
  78    *
  79    * The operation is deferred to the active toolkit.
  80    *
  81    * @param string $operation
  82    *   The operation to be performed against the image.
  83    * @param array $arguments
  84    *   (optional) An associative array of arguments to be passed to the toolkit
  85    *   operation; for instance,
  86    *   @code
  87    *     ['width' => 50, 'height' => 100, 'upscale' => TRUE]
  88    *   @endcode
  89    *   Defaults to an empty array.
  90    *
  91    * @return bool
  92    *   TRUE on success, FALSE on failure.
  93    */
  94   public function apply($operation, array $arguments = []);
  95
  96   /**
  97    * Closes the image and saves the changes to a file.
  98    *
  99    * @param string|null $destination
 100    *   (optional) Destination path where the image should be saved. If it is empty
 101    *   the original image file will be overwritten.
 102    *
 103    * @return bool
 104    *   TRUE on success, FALSE on failure.
 105    *
 106    * @see \Drupal\Core\ImageToolkit\ImageToolkitInterface::save()
 107    */
 108   public function save($destination = NULL);
 109
 110   /**
 111    * Prepares a new image, without loading it from a file.
 112    *
 113    * For a working example, see
 114    * \Drupal\system\Plugin\ImageToolkit\Operation\gd\CreateNew.
 115    *
 116    * @param int $width
 117    *   The width of the new image, in pixels.
 118    * @param int $height
 119    *   The height of the new image, in pixels.
 120    * @param string $extension
 121    *   (optional) The extension of the image file (for instance, 'png', 'gif',
 122    *   etc.). Allowed values depend on the implementation of the image toolkit.
 123    *   Defaults to 'png'.
 124    * @param string $transparent_color
 125    *   (optional) The hexadecimal string representing the color to be used
 126    *   for transparency, needed for GIF images. Defaults to '#ffffff' (white).
 127    *
 128    * @return bool
 129    *   TRUE on success, FALSE on failure.
 130    */
 131   public function createNew($width, $height, $extension = 'png', $transparent_color = '#ffffff');
 132
 133   /**
 134    * Scales an image while maintaining aspect ratio.
 135    *
 136    * The resulting image can be smaller for one or both target dimensions.
 137    *
 138    * @param int|null $width
 139    *   The target width, in pixels. If this value is null then the scaling will
 140    *   be based only on the height value.
 141    * @param int|null $height
 142    *   (optional) The target height, in pixels. If this value is null then the
 143    *   scaling will be based only on the width value.
 144    * @param bool $upscale
 145    *   (optional) Boolean indicating that files smaller than the dimensions will
 146    *   be scaled up. This generally results in a low quality image.
 147    *
 148    * @return bool
 149    *   TRUE on success, FALSE on failure.
 150    */
 151   public function scale($width, $height = NULL, $upscale = FALSE);
 152
 153   /**
 154    * Scales an image to the exact width and height given.
 155    *
 156    * This function achieves the target aspect ratio by cropping the original
 157    * image equally on both sides, or equally on the top and bottom. This
 158    * function is useful to create uniform sized avatars from larger images.
 159    *
 160    * The resulting image always has the exact target dimensions.
 161    *
 162    * @param int $width
 163    *   The target width, in pixels.
 164    * @param int $height
 165    *   The target height, in pixels.
 166    *
 167    * @return bool
 168    *   TRUE on success, FALSE on failure.
 169    */
 170   public function scaleAndCrop($width, $height);
 171
 172   /**
 173    * Instructs the toolkit to save the image in the format specified by the
 174    * extension.
 175    *
 176    * @param string $extension
 177    *   The extension to convert to (for instance, 'jpeg' or 'png'). Allowed
 178    *   values depend on the current image toolkit.
 179    *
 180    * @return bool
 181    *   TRUE on success, FALSE on failure.
 182    *
 183    * @see \Drupal\Core\ImageToolkit\ImageToolkitInterface::getSupportedExtensions()
 184    */
 185   public function convert($extension);
 186
 187   /**
 188    * Crops an image to a rectangle specified by the given dimensions.
 189    *
 190    * @param int $x
 191    *   The top left coordinate, in pixels, of the crop area (x axis value).
 192    * @param int $y
 193    *   The top left coordinate, in pixels, of the crop area (y axis value).
 194    * @param int $width
 195    *   The target width, in pixels.
 196    * @param int $height
 197    *   The target height, in pixels.
 198    *
 199    * @return bool
 200    *   TRUE on success, FALSE on failure.
 201    */
 202   public function crop($x, $y, $width, $height = NULL);
 203
 204   /**
 205    * Resizes an image to the given dimensions (ignoring aspect ratio).
 206    *
 207    * @param int $width
 208    *   The target width, in pixels.
 209    * @param int $height
 210    *   The target height, in pixels.
 211    *
 212    * @return bool
 213    *   TRUE on success, FALSE on failure.
 214    */
 215   public function resize($width, $height);
 216
 217   /**
 218    * Converts an image to grayscale.
 219    *
 220    * @return bool
 221    *   TRUE on success, FALSE on failure.
 222    */
 223   public function desaturate();
 224
 225   /**
 226    * Rotates an image by the given number of degrees.
 227    *
 228    * @param float $degrees
 229    *   The number of (clockwise) degrees to rotate the image.
 230    * @param string|null $background
 231    *   (optional) An hexadecimal integer specifying the background color to use
 232    *   for the uncovered area of the image after the rotation; for example,
 233    *   0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When
 234    *   NULL (the default) is specified, for images that support transparency,
 235    *   this will default to transparent; otherwise, it will default to white.
 236    *
 237    * @return bool
 238    *   TRUE on success, FALSE on failure.
 239    */
 240   public function rotate($degrees, $background = NULL);
 241
 242 }