annotate core/lib/Drupal/Core/ImageToolkit/ImageToolkitInterface.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\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 }