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 }
|