aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/ImageToolkit/ImageToolkitInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\ImageToolkit;
   4
   5 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
   6 use Drupal\Core\Plugin\PluginFormInterface;
   7 use Drupal\Component\Plugin\PluginInspectionInterface;
   8
   9 /**
  10  * @defgroup image Image toolkits
  11  * @{
  12  * Functions for image file manipulations.
  13  *
  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.
  18  *
  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
  24  * software.
  25  *
  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.
  29  *
  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.
  34  */
  35
  36 /**
  37  * Defines an interface for image toolkits.
  38  *
  39  * An image toolkit provides common image file manipulations like scaling,
  40  * cropping, and rotating.
  41  *
  42  * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkit
  43  * @see \Drupal\Core\ImageToolkit\ImageToolkitBase
  44  * @see \Drupal\Core\ImageToolkit\ImageToolkitManager
  45  * @see plugin_api
  46  */
  47 interface ImageToolkitInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
  48
  49   /**
  50    * Sets the source path of the image file.
  51    *
  52    * @param string $source
  53    *   The source path of the image file.
  54    *
  55    * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
  56    *   An instance of the current toolkit object.
  57    *
  58    * @throws \BadMethodCallException
  59    *   After being set initially, the source image cannot be changed.
  60    */
  61   public function setSource($source);
  62
  63   /**
  64    * Gets the source path of the image file.
  65    *
  66    * @return string
  67    *   The source path of the image file, or an empty string if the source is
  68    *   not set.
  69    */
  70   public function getSource();
  71
  72   /**
  73    * Checks if the image is valid.
  74    *
  75    * @return bool
  76    *   TRUE if the image toolkit is currently handling a valid image, FALSE
  77    *   otherwise.
  78    */
  79   public function isValid();
  80
  81   /**
  82    * Writes an image resource to a destination file.
  83    *
  84    * @param string $destination
  85    *   A string file URI or path where the image should be saved.
  86    *
  87    * @return bool
  88    *   TRUE on success, FALSE on failure.
  89    */
  90   public function save($destination);
  91
  92   /**
  93    * Determines if a file contains a valid image.
  94    *
  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
  97    * installed.
  98    *
  99    * @return bool
 100    *   TRUE if the file could be found and is an image, FALSE otherwise.
 101    */
 102   public function parseFile();
 103
 104   /**
 105    * Returns the height of the image.
 106    *
 107    * @return int|null
 108    *   The height of the image, or NULL if the image is invalid.
 109    */
 110   public function getHeight();
 111
 112   /**
 113    * Returns the width of the image.
 114    *
 115    * @return int|null
 116    *   The width of the image, or NULL if the image is invalid.
 117    */
 118   public function getWidth();
 119
 120   /**
 121    * Returns the MIME type of the image file.
 122    *
 123    * @return string
 124    *   The MIME type of the image file, or an empty string if the image is
 125    *   invalid.
 126    */
 127   public function getMimeType();
 128
 129   /**
 130    * Gets toolkit requirements in a format suitable for hook_requirements().
 131    *
 132    * @return array
 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.
 138    *
 139    * @see hook_requirements()
 140    */
 141   public function getRequirements();
 142
 143   /**
 144    * Verifies that the Image Toolkit is set up correctly.
 145    *
 146    * @return bool
 147    *   TRUE if the toolkit is available on this machine, FALSE otherwise.
 148    */
 149   public static function isAvailable();
 150
 151   /**
 152    * Returns a list of image file extensions supported by the toolkit.
 153    *
 154    * @return array
 155    *   An array of supported image file extensions (e.g. png/jpeg/gif).
 156    */
 157   public static function getSupportedExtensions();
 158
 159   /**
 160    * Applies a toolkit operation to an image.
 161    *
 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).
 168    *
 169    * @return bool
 170    *   TRUE if the operation was performed successfully, FALSE otherwise.
 171    */
 172   public function apply($operation, array $arguments = []);
 173
 174 }