Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\ImageToolkit;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
|
Chris@0
|
6 use Drupal\Core\Plugin\PluginFormInterface;
|
Chris@0
|
7 use Drupal\Component\Plugin\PluginInspectionInterface;
|
Chris@0
|
8
|
Chris@0
|
9 /**
|
Chris@0
|
10 * @defgroup image Image toolkits
|
Chris@0
|
11 * @{
|
Chris@0
|
12 * Functions for image file manipulations.
|
Chris@0
|
13 *
|
Chris@0
|
14 * Drupal's image toolkits provide an abstraction layer for common image file
|
Chris@0
|
15 * manipulations like scaling, cropping, and rotating. The abstraction frees
|
Chris@0
|
16 * module authors from the need to support multiple image libraries, and it
|
Chris@0
|
17 * allows site administrators to choose the library that's best for them.
|
Chris@0
|
18 *
|
Chris@0
|
19 * PHP includes the GD library by default so a GD toolkit is installed with
|
Chris@0
|
20 * Drupal. Other toolkits like ImageMagick are available from contrib modules.
|
Chris@0
|
21 * GD works well for small images, but using it with larger files may cause PHP
|
Chris@0
|
22 * to run out of memory. In contrast the ImageMagick library does not suffer
|
Chris@0
|
23 * from this problem, but it requires the ISP to have installed additional
|
Chris@0
|
24 * software.
|
Chris@0
|
25 *
|
Chris@0
|
26 * Image toolkits are discovered using the Plugin system using
|
Chris@0
|
27 * \Drupal\Core\ImageToolkit\ImageToolkitManager. The toolkit must then be
|
Chris@0
|
28 * enabled using the admin/config/media/image-toolkit form.
|
Chris@0
|
29 *
|
Chris@0
|
30 * Only one toolkit may be selected at a time. If a module author wishes to call
|
Chris@0
|
31 * a specific toolkit they can check that it is installed by calling
|
Chris@0
|
32 * \Drupal\Core\ImageToolkit\ImageToolkitManager::getAvailableToolkits(), and
|
Chris@0
|
33 * then calling its functions directly.
|
Chris@0
|
34 */
|
Chris@0
|
35
|
Chris@0
|
36 /**
|
Chris@0
|
37 * Defines an interface for image toolkits.
|
Chris@0
|
38 *
|
Chris@0
|
39 * An image toolkit provides common image file manipulations like scaling,
|
Chris@0
|
40 * cropping, and rotating.
|
Chris@0
|
41 *
|
Chris@0
|
42 * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkit
|
Chris@0
|
43 * @see \Drupal\Core\ImageToolkit\ImageToolkitBase
|
Chris@0
|
44 * @see \Drupal\Core\ImageToolkit\ImageToolkitManager
|
Chris@0
|
45 * @see plugin_api
|
Chris@0
|
46 */
|
Chris@0
|
47 interface ImageToolkitInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
|
Chris@0
|
48
|
Chris@0
|
49 /**
|
Chris@0
|
50 * Sets the source path of the image file.
|
Chris@0
|
51 *
|
Chris@0
|
52 * @param string $source
|
Chris@0
|
53 * The source path of the image file.
|
Chris@0
|
54 *
|
Chris@0
|
55 * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
|
Chris@0
|
56 * An instance of the current toolkit object.
|
Chris@0
|
57 *
|
Chris@0
|
58 * @throws \BadMethodCallException
|
Chris@0
|
59 * After being set initially, the source image cannot be changed.
|
Chris@0
|
60 */
|
Chris@0
|
61 public function setSource($source);
|
Chris@0
|
62
|
Chris@0
|
63 /**
|
Chris@0
|
64 * Gets the source path of the image file.
|
Chris@0
|
65 *
|
Chris@0
|
66 * @return string
|
Chris@0
|
67 * The source path of the image file, or an empty string if the source is
|
Chris@0
|
68 * not set.
|
Chris@0
|
69 */
|
Chris@0
|
70 public function getSource();
|
Chris@0
|
71
|
Chris@0
|
72 /**
|
Chris@0
|
73 * Checks if the image is valid.
|
Chris@0
|
74 *
|
Chris@0
|
75 * @return bool
|
Chris@0
|
76 * TRUE if the image toolkit is currently handling a valid image, FALSE
|
Chris@0
|
77 * otherwise.
|
Chris@0
|
78 */
|
Chris@0
|
79 public function isValid();
|
Chris@0
|
80
|
Chris@0
|
81 /**
|
Chris@0
|
82 * Writes an image resource to a destination file.
|
Chris@0
|
83 *
|
Chris@0
|
84 * @param string $destination
|
Chris@0
|
85 * A string file URI or path where the image should be saved.
|
Chris@0
|
86 *
|
Chris@0
|
87 * @return bool
|
Chris@0
|
88 * TRUE on success, FALSE on failure.
|
Chris@0
|
89 */
|
Chris@0
|
90 public function save($destination);
|
Chris@0
|
91
|
Chris@0
|
92 /**
|
Chris@0
|
93 * Determines if a file contains a valid image.
|
Chris@0
|
94 *
|
Chris@0
|
95 * Drupal supports GIF, JPG and PNG file formats when used with the GD
|
Chris@0
|
96 * toolkit, and may support others, depending on which toolkits are
|
Chris@0
|
97 * installed.
|
Chris@0
|
98 *
|
Chris@0
|
99 * @return bool
|
Chris@0
|
100 * TRUE if the file could be found and is an image, FALSE otherwise.
|
Chris@0
|
101 */
|
Chris@0
|
102 public function parseFile();
|
Chris@0
|
103
|
Chris@0
|
104 /**
|
Chris@0
|
105 * Returns the height of the image.
|
Chris@0
|
106 *
|
Chris@0
|
107 * @return int|null
|
Chris@0
|
108 * The height of the image, or NULL if the image is invalid.
|
Chris@0
|
109 */
|
Chris@0
|
110 public function getHeight();
|
Chris@0
|
111
|
Chris@0
|
112 /**
|
Chris@0
|
113 * Returns the width of the image.
|
Chris@0
|
114 *
|
Chris@0
|
115 * @return int|null
|
Chris@0
|
116 * The width of the image, or NULL if the image is invalid.
|
Chris@0
|
117 */
|
Chris@0
|
118 public function getWidth();
|
Chris@0
|
119
|
Chris@0
|
120 /**
|
Chris@0
|
121 * Returns the MIME type of the image file.
|
Chris@0
|
122 *
|
Chris@0
|
123 * @return string
|
Chris@0
|
124 * The MIME type of the image file, or an empty string if the image is
|
Chris@0
|
125 * invalid.
|
Chris@0
|
126 */
|
Chris@0
|
127 public function getMimeType();
|
Chris@0
|
128
|
Chris@0
|
129 /**
|
Chris@0
|
130 * Gets toolkit requirements in a format suitable for hook_requirements().
|
Chris@0
|
131 *
|
Chris@0
|
132 * @return array
|
Chris@0
|
133 * An associative requirements array as is returned by hook_requirements().
|
Chris@0
|
134 * If the toolkit claims no requirements to the system, returns an empty
|
Chris@0
|
135 * array. The array can have arbitrary keys and they do not have to be
|
Chris@0
|
136 * prefixed by e.g. the module name or toolkit ID, as the system will make
|
Chris@0
|
137 * the keys globally unique.
|
Chris@0
|
138 *
|
Chris@0
|
139 * @see hook_requirements()
|
Chris@0
|
140 */
|
Chris@0
|
141 public function getRequirements();
|
Chris@0
|
142
|
Chris@0
|
143 /**
|
Chris@0
|
144 * Verifies that the Image Toolkit is set up correctly.
|
Chris@0
|
145 *
|
Chris@0
|
146 * @return bool
|
Chris@0
|
147 * TRUE if the toolkit is available on this machine, FALSE otherwise.
|
Chris@0
|
148 */
|
Chris@0
|
149 public static function isAvailable();
|
Chris@0
|
150
|
Chris@0
|
151 /**
|
Chris@0
|
152 * Returns a list of image file extensions supported by the toolkit.
|
Chris@0
|
153 *
|
Chris@0
|
154 * @return array
|
Chris@0
|
155 * An array of supported image file extensions (e.g. png/jpeg/gif).
|
Chris@0
|
156 */
|
Chris@0
|
157 public static function getSupportedExtensions();
|
Chris@0
|
158
|
Chris@0
|
159 /**
|
Chris@0
|
160 * Applies a toolkit operation to an image.
|
Chris@0
|
161 *
|
Chris@0
|
162 * @param string $operation
|
Chris@0
|
163 * The toolkit operation to be processed.
|
Chris@0
|
164 * @param array $arguments
|
Chris@0
|
165 * An associative array of arguments to be passed to the toolkit
|
Chris@0
|
166 * operation, e.g. array('width' => 50, 'height' => 100,
|
Chris@0
|
167 * 'upscale' => TRUE).
|
Chris@0
|
168 *
|
Chris@0
|
169 * @return bool
|
Chris@0
|
170 * TRUE if the operation was performed successfully, FALSE otherwise.
|
Chris@0
|
171 */
|
Chris@0
|
172 public function apply($operation, array $arguments = []);
|
Chris@0
|
173
|
Chris@0
|
174 }
|