3 namespace Drupal\Core\ImageToolkit;
5 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
6 use Drupal\Core\Plugin\PluginFormInterface;
7 use Drupal\Component\Plugin\PluginInspectionInterface;
10 * @defgroup image Image toolkits
12 * Functions for image file manipulations.
14 * Drupal's image toolkits provide an abstraction layer for common image file
15 * manipulations like scaling, cropping, and rotating. The abstraction frees
16 * module authors from the need to support multiple image libraries, and it
17 * allows site administrators to choose the library that's best for them.
19 * PHP includes the GD library by default so a GD toolkit is installed with
20 * Drupal. Other toolkits like ImageMagick are available from contrib modules.
21 * GD works well for small images, but using it with larger files may cause PHP
22 * to run out of memory. In contrast the ImageMagick library does not suffer
23 * from this problem, but it requires the ISP to have installed additional
26 * Image toolkits are discovered using the Plugin system using
27 * \Drupal\Core\ImageToolkit\ImageToolkitManager. The toolkit must then be
28 * enabled using the admin/config/media/image-toolkit form.
30 * Only one toolkit may be selected at a time. If a module author wishes to call
31 * a specific toolkit they can check that it is installed by calling
32 * \Drupal\Core\ImageToolkit\ImageToolkitManager::getAvailableToolkits(), and
33 * then calling its functions directly.
37 * Defines an interface for image toolkits.
39 * An image toolkit provides common image file manipulations like scaling,
40 * cropping, and rotating.
42 * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkit
43 * @see \Drupal\Core\ImageToolkit\ImageToolkitBase
44 * @see \Drupal\Core\ImageToolkit\ImageToolkitManager
47 interface ImageToolkitInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
50 * Sets the source path of the image file.
52 * @param string $source
53 * The source path of the image file.
55 * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
56 * An instance of the current toolkit object.
58 * @throws \BadMethodCallException
59 * After being set initially, the source image cannot be changed.
61 public function setSource($source);
64 * Gets the source path of the image file.
67 * The source path of the image file, or an empty string if the source is
70 public function getSource();
73 * Checks if the image is valid.
76 * TRUE if the image toolkit is currently handling a valid image, FALSE
79 public function isValid();
82 * Writes an image resource to a destination file.
84 * @param string $destination
85 * A string file URI or path where the image should be saved.
88 * TRUE on success, FALSE on failure.
90 public function save($destination);
93 * Determines if a file contains a valid image.
95 * Drupal supports GIF, JPG and PNG file formats when used with the GD
96 * toolkit, and may support others, depending on which toolkits are
100 * TRUE if the file could be found and is an image, FALSE otherwise.
102 public function parseFile();
105 * Returns the height of the image.
108 * The height of the image, or NULL if the image is invalid.
110 public function getHeight();
113 * Returns the width of the image.
116 * The width of the image, or NULL if the image is invalid.
118 public function getWidth();
121 * Returns the MIME type of the image file.
124 * The MIME type of the image file, or an empty string if the image is
127 public function getMimeType();
130 * Gets toolkit requirements in a format suitable for hook_requirements().
133 * An associative requirements array as is returned by hook_requirements().
134 * If the toolkit claims no requirements to the system, returns an empty
135 * array. The array can have arbitrary keys and they do not have to be
136 * prefixed by e.g. the module name or toolkit ID, as the system will make
137 * the keys globally unique.
139 * @see hook_requirements()
141 public function getRequirements();
144 * Verifies that the Image Toolkit is set up correctly.
147 * TRUE if the toolkit is available on this machine, FALSE otherwise.
149 public static function isAvailable();
152 * Returns a list of image file extensions supported by the toolkit.
155 * An array of supported image file extensions (e.g. png/jpeg/gif).
157 public static function getSupportedExtensions();
160 * Applies a toolkit operation to an image.
162 * @param string $operation
163 * The toolkit operation to be processed.
164 * @param array $arguments
165 * An associative array of arguments to be passed to the toolkit
166 * operation, e.g. array('width' => 50, 'height' => 100,
167 * 'upscale' => TRUE).
170 * TRUE if the operation was performed successfully, FALSE otherwise.
172 public function apply($operation, array $arguments = []);