ImageInterface.php

<?php

namespace Drupal\Core\Image;


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

}