Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\ImageToolkit;
Chris@0: 
Chris@0: use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
Chris@0: use Drupal\Core\Plugin\PluginFormInterface;
Chris@0: use Drupal\Component\Plugin\PluginInspectionInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup image Image toolkits
Chris@0:  * @{
Chris@0:  * Functions for image file manipulations.
Chris@0:  *
Chris@0:  * Drupal's image toolkits provide an abstraction layer for common image file
Chris@0:  * manipulations like scaling, cropping, and rotating. The abstraction frees
Chris@0:  * module authors from the need to support multiple image libraries, and it
Chris@0:  * allows site administrators to choose the library that's best for them.
Chris@0:  *
Chris@0:  * PHP includes the GD library by default so a GD toolkit is installed with
Chris@0:  * Drupal. Other toolkits like ImageMagick are available from contrib modules.
Chris@0:  * GD works well for small images, but using it with larger files may cause PHP
Chris@0:  * to run out of memory. In contrast the ImageMagick library does not suffer
Chris@0:  * from this problem, but it requires the ISP to have installed additional
Chris@0:  * software.
Chris@0:  *
Chris@0:  * Image toolkits are discovered using the Plugin system using
Chris@0:  * \Drupal\Core\ImageToolkit\ImageToolkitManager. The toolkit must then be
Chris@0:  * enabled using the admin/config/media/image-toolkit form.
Chris@0:  *
Chris@0:  * Only one toolkit may be selected at a time. If a module author wishes to call
Chris@0:  * a specific toolkit they can check that it is installed by calling
Chris@0:  * \Drupal\Core\ImageToolkit\ImageToolkitManager::getAvailableToolkits(), and
Chris@0:  * then calling its functions directly.
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for image toolkits.
Chris@0:  *
Chris@0:  * An image toolkit provides common image file manipulations like scaling,
Chris@0:  * cropping, and rotating.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkit
Chris@0:  * @see \Drupal\Core\ImageToolkit\ImageToolkitBase
Chris@0:  * @see \Drupal\Core\ImageToolkit\ImageToolkitManager
Chris@0:  * @see plugin_api
Chris@0:  */
Chris@0: interface ImageToolkitInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the source path of the image file.
Chris@0:    *
Chris@0:    * @param string $source
Chris@0:    *   The source path of the image file.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0:    *   An instance of the current toolkit object.
Chris@0:    *
Chris@0:    * @throws \BadMethodCallException
Chris@0:    *   After being set initially, the source image cannot be changed.
Chris@0:    */
Chris@0:   public function setSource($source);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the source path of the image file.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The source path of the image file, or an empty string if the source is
Chris@0:    *   not set.
Chris@0:    */
Chris@0:   public function getSource();
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks if the image is valid.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the image toolkit is currently handling a valid image, FALSE
Chris@0:    *   otherwise.
Chris@0:    */
Chris@0:   public function isValid();
Chris@0: 
Chris@0:   /**
Chris@0:    * Writes an image resource to a destination file.
Chris@0:    *
Chris@0:    * @param string $destination
Chris@0:    *   A string file URI or path where the image should be saved.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function save($destination);
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines if a file contains a valid image.
Chris@0:    *
Chris@0:    * Drupal supports GIF, JPG and PNG file formats when used with the GD
Chris@0:    * toolkit, and may support others, depending on which toolkits are
Chris@0:    * installed.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the file could be found and is an image, FALSE otherwise.
Chris@0:    */
Chris@0:   public function parseFile();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the height of the image.
Chris@0:    *
Chris@0:    * @return int|null
Chris@0:    *   The height of the image, or NULL if the image is invalid.
Chris@0:    */
Chris@0:   public function getHeight();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the width of the image.
Chris@0:    *
Chris@0:    * @return int|null
Chris@0:    *   The width of the image, or NULL if the image is invalid.
Chris@0:    */
Chris@0:   public function getWidth();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the MIME type of the image file.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The MIME type of the image file, or an empty string if the image is
Chris@0:    *   invalid.
Chris@0:    */
Chris@0:   public function getMimeType();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets toolkit requirements in a format suitable for hook_requirements().
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An associative requirements array as is returned by hook_requirements().
Chris@0:    *   If the toolkit claims no requirements to the system, returns an empty
Chris@0:    *   array. The array can have arbitrary keys and they do not have to be
Chris@0:    *   prefixed by e.g. the module name or toolkit ID, as the system will make
Chris@0:    *   the keys globally unique.
Chris@0:    *
Chris@0:    * @see hook_requirements()
Chris@0:    */
Chris@0:   public function getRequirements();
Chris@0: 
Chris@0:   /**
Chris@0:    * Verifies that the Image Toolkit is set up correctly.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the toolkit is available on this machine, FALSE otherwise.
Chris@0:    */
Chris@0:   public static function isAvailable();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a list of image file extensions supported by the toolkit.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of supported image file extensions (e.g. png/jpeg/gif).
Chris@0:    */
Chris@0:   public static function getSupportedExtensions();
Chris@0: 
Chris@0:   /**
Chris@0:    * Applies a toolkit operation to an image.
Chris@0:    *
Chris@0:    * @param string $operation
Chris@0:    *   The toolkit operation to be processed.
Chris@0:    * @param array $arguments
Chris@0:    *   An associative array of arguments to be passed to the toolkit
Chris@0:    *   operation, e.g. array('width' => 50, 'height' => 100,
Chris@0:    *   'upscale' => TRUE).
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the operation was performed successfully, FALSE otherwise.
Chris@0:    */
Chris@0:   public function apply($operation, array $arguments = []);
Chris@0: 
Chris@0: }