Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Image;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides an interface for image objects.
Chris@0:  */
Chris@0: interface ImageInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks if the image is valid.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the image object contains a valid image, FALSE otherwise.
Chris@0:    */
Chris@0:   public function isValid();
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 size of the image file.
Chris@0:    *
Chris@0:    * @return int|null
Chris@0:    *   The size of the file in bytes, or NULL if the image is invalid.
Chris@0:    */
Chris@0:   public function getFileSize();
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:    * Retrieves the source path of the image file.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The source path of the image file. An empty string if the source is
Chris@0:    *   not set.
Chris@0:    */
Chris@0:   public function getSource();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the image toolkit used for this image file.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0:    *   The image toolkit.
Chris@0:    */
Chris@0:   public function getToolkit();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the ID of the image toolkit used for this image file.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The ID of the image toolkit.
Chris@0:    */
Chris@0:   public function getToolkitId();
Chris@0: 
Chris@0:   /**
Chris@0:    * Applies a toolkit operation to the image.
Chris@0:    *
Chris@0:    * The operation is deferred to the active toolkit.
Chris@0:    *
Chris@0:    * @param string $operation
Chris@0:    *   The operation to be performed against the image.
Chris@0:    * @param array $arguments
Chris@0:    *   (optional) An associative array of arguments to be passed to the toolkit
Chris@0:    *   operation; for instance,
Chris@0:    *   @code
Chris@0:    *     ['width' => 50, 'height' => 100, 'upscale' => TRUE]
Chris@0:    *   @endcode
Chris@0:    *   Defaults to an empty array.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function apply($operation, array $arguments = []);
Chris@0: 
Chris@0:   /**
Chris@0:    * Closes the image and saves the changes to a file.
Chris@0:    *
Chris@0:    * @param string|null $destination
Chris@0:    *   (optional) Destination path where the image should be saved. If it is empty
Chris@0:    *   the original image file will be overwritten.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\ImageToolkit\ImageToolkitInterface::save()
Chris@0:    */
Chris@0:   public function save($destination = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Prepares a new image, without loading it from a file.
Chris@0:    *
Chris@0:    * For a working example, see
Chris@0:    * \Drupal\system\Plugin\ImageToolkit\Operation\gd\CreateNew.
Chris@0:    *
Chris@0:    * @param int $width
Chris@0:    *   The width of the new image, in pixels.
Chris@0:    * @param int $height
Chris@0:    *   The height of the new image, in pixels.
Chris@0:    * @param string $extension
Chris@0:    *   (optional) The extension of the image file (for instance, 'png', 'gif',
Chris@0:    *   etc.). Allowed values depend on the implementation of the image toolkit.
Chris@0:    *   Defaults to 'png'.
Chris@0:    * @param string $transparent_color
Chris@0:    *   (optional) The hexadecimal string representing the color to be used
Chris@0:    *   for transparency, needed for GIF images. Defaults to '#ffffff' (white).
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function createNew($width, $height, $extension = 'png', $transparent_color = '#ffffff');
Chris@0: 
Chris@0:   /**
Chris@0:    * Scales an image while maintaining aspect ratio.
Chris@0:    *
Chris@0:    * The resulting image can be smaller for one or both target dimensions.
Chris@0:    *
Chris@0:    * @param int|null $width
Chris@0:    *   The target width, in pixels. If this value is null then the scaling will
Chris@0:    *   be based only on the height value.
Chris@0:    * @param int|null $height
Chris@0:    *   (optional) The target height, in pixels. If this value is null then the
Chris@0:    *   scaling will be based only on the width value.
Chris@0:    * @param bool $upscale
Chris@0:    *   (optional) Boolean indicating that files smaller than the dimensions will
Chris@0:    *   be scaled up. This generally results in a low quality image.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function scale($width, $height = NULL, $upscale = FALSE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Scales an image to the exact width and height given.
Chris@0:    *
Chris@0:    * This function achieves the target aspect ratio by cropping the original
Chris@0:    * image equally on both sides, or equally on the top and bottom. This
Chris@0:    * function is useful to create uniform sized avatars from larger images.
Chris@0:    *
Chris@0:    * The resulting image always has the exact target dimensions.
Chris@0:    *
Chris@0:    * @param int $width
Chris@0:    *   The target width, in pixels.
Chris@0:    * @param int $height
Chris@0:    *   The target height, in pixels.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function scaleAndCrop($width, $height);
Chris@0: 
Chris@0:   /**
Chris@0:    * Instructs the toolkit to save the image in the format specified by the
Chris@0:    * extension.
Chris@0:    *
Chris@0:    * @param string $extension
Chris@0:    *   The extension to convert to (for instance, 'jpeg' or 'png'). Allowed
Chris@0:    *   values depend on the current image toolkit.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\ImageToolkit\ImageToolkitInterface::getSupportedExtensions()
Chris@0:    */
Chris@0:   public function convert($extension);
Chris@0: 
Chris@0:   /**
Chris@0:    * Crops an image to a rectangle specified by the given dimensions.
Chris@0:    *
Chris@0:    * @param int $x
Chris@0:    *   The top left coordinate, in pixels, of the crop area (x axis value).
Chris@0:    * @param int $y
Chris@0:    *   The top left coordinate, in pixels, of the crop area (y axis value).
Chris@0:    * @param int $width
Chris@0:    *   The target width, in pixels.
Chris@0:    * @param int $height
Chris@0:    *   The target height, in pixels.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function crop($x, $y, $width, $height = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Resizes an image to the given dimensions (ignoring aspect ratio).
Chris@0:    *
Chris@0:    * @param int $width
Chris@0:    *   The target width, in pixels.
Chris@0:    * @param int $height
Chris@0:    *   The target height, in pixels.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function resize($width, $height);
Chris@0: 
Chris@0:   /**
Chris@0:    * Converts an image to grayscale.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function desaturate();
Chris@0: 
Chris@0:   /**
Chris@0:    * Rotates an image by the given number of degrees.
Chris@0:    *
Chris@0:    * @param float $degrees
Chris@0:    *   The number of (clockwise) degrees to rotate the image.
Chris@0:    * @param string|null $background
Chris@0:    *   (optional) An hexadecimal integer specifying the background color to use
Chris@0:    *   for the uncovered area of the image after the rotation; for example,
Chris@0:    *   0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When
Chris@0:    *   NULL (the default) is specified, for images that support transparency,
Chris@0:    *   this will default to transparent; otherwise, it will default to white.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on success, FALSE on failure.
Chris@0:    */
Chris@0:   public function rotate($degrees, $background = NULL);
Chris@0: 
Chris@0: }