annotate core/lib/Drupal/Core/Image/ImageInterface.php @ 19:fa3358dc1485 tip

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