# Class yii\imagine\Image

Inheritance | yii\imagine\Image » yii\imagine\BaseImage
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2-imagine/blob/master/Image.php

Image implements most commonly used image manipulation functions using the Imagine library.

Example of use:

    // generate a thumbnail image
    Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
        ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$driver | array|string | The driver to use. | yii\imagine\BaseImage
$thumbnailBackgroundAlpha | string | Background alpha (transparency) to use when creating thumbnails in `ImageInterface::THUMBNAIL_INSET` mode with both width and height specified. | yii\imagine\BaseImage
$thumbnailBackgroundColor | string | Background color to use when creating thumbnails in `ImageInterface::THUMBNAIL_INSET` mode with both width and height specified. | yii\imagine\BaseImage

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
autorotate() | Rotates an image automatically based on EXIF information. | yii\imagine\BaseImage
crop() | Crops an image. | yii\imagine\BaseImage
frame() | Adds a frame around of the image. Please note that the image size will increase by `$margin` x 2. | yii\imagine\BaseImage
getBox() | Returns box for an image to be created. | yii\imagine\BaseImage
getImagine() | Returns the `Imagine` object that supports various image manipulations. | yii\imagine\BaseImage
getThumbnailBox() | Returns box for a thumbnail to be created. If one of the dimensions is set to `null`, another one is calculated automatically based on width to height ratio of original image box. | yii\imagine\BaseImage
isUpscaling() | Checks if upscaling is going to happen | yii\imagine\BaseImage
resize() | Resizes an image. | yii\imagine\BaseImage
setImagine() |  | yii\imagine\BaseImage
text() | Draws a text string on an existing image. | yii\imagine\BaseImage
thumbnail() | Creates a thumbnail image. | yii\imagine\BaseImage
watermark() | Adds a watermark to an existing image. | yii\imagine\BaseImage

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
createImagine() | Creates an `Imagine` object based on the specified $driver. | yii\imagine\BaseImage
ensureImageInterfaceInstance() | Takes either file path or ImageInterface. In case of file path, creates an instance of ImageInterface from it. | yii\imagine\BaseImage

## Constants

Hide inherited constants

Constant | Value | Description | Defined By
--- | --- | --- | ---
DRIVER_GD2 | 'gd2' | GD2 driver definition for Imagine implementation using the GD library. | yii\imagine\BaseImage
DRIVER_GMAGICK | 'gmagick' | Gmagick driver definition. | yii\imagine\BaseImage
DRIVER_IMAGICK | 'imagick' | Imagick driver definition. | yii\imagine\BaseImage

## Method Details

Hide inherited methods

autorotate() public static method (available since version 2.1.0)

Defined in: yii\imagine\BaseImage::autorotate()

Rotates an image automatically based on EXIF information.

public static \Imagine\Image\ImageInterface autorotate ( $image, $color = '000000' )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$color | string |

Source code

                    public static function autorotate($image, $color = '000000')
    {
        return (new Autorotate($color))->apply(static::ensureImageInterfaceInstance($image));
    }

createImagine() protected static method

Defined in: yii\imagine\BaseImage::createImagine()

Creates an `Imagine` object based on the specified $driver.

protected static \Imagine\Image\ImagineInterface createImagine ( )
return | \Imagine\Image\ImagineInterface | The new `Imagine` object
throws | yii\base\InvalidConfigException | if $driver is unknown or the system doesn't support any $driver.

Source code

                    protected static function createImagine()
    {
        foreach ((array) static::$driver as $driver) {
            switch ($driver) {
                case self::DRIVER_GMAGICK:
                    if (class_exists('Gmagick', false)) {
                        return new \Imagine\Gmagick\Imagine();
                    }
                    break;
                case self::DRIVER_IMAGICK:
                    if (class_exists('Imagick', false)) {
                        return new \Imagine\Imagick\Imagine();
                    }
                    break;
                case self::DRIVER_GD2:
                    if (function_exists('gd_info')) {
                        return new \Imagine\Gd\Imagine();
                    }
                    break;
                default:
                    throw new InvalidConfigException("Unknown driver: $driver");
            }
        }
        throw new InvalidConfigException('Your system does not support any of these drivers: ' . implode(',', (array) static::$driver));
    }

crop() public static method

Defined in: yii\imagine\BaseImage::crop()

Crops an image.

For example:

    $obj->crop('path\to\image.jpg', 200, 200, [5, 5]);

    $point = new \Imagine\Image\Point(5, 5);
    $obj->crop('path\to\image.jpg', 200, 200, $point);

public static \Imagine\Image\ImageInterface crop ( $image, $width, $height, array $start = [0, 0] )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$width | integer | The crop width
$height | integer | The crop height
$start | array | The starting point. This must be an array with two elements representing `x` and `y` coordinates.
throws | yii\base\InvalidParamException | if the `$start` parameter is invalid

Source code

                    public static function crop($image, $width, $height, array $start = [0, 0])
    {
        if (!isset($start[0], $start[1])) {
            throw new InvalidParamException('$start must be an array of two elements.');
        }
        return static::ensureImageInterfaceInstance($image)
            ->copy()
            ->crop(new Point($start[0], $start[1]), new Box($width, $height));
    }

ensureImageInterfaceInstance() protected static method (available since version 2.1.0)

Defined in: yii\imagine\BaseImage::ensureImageInterfaceInstance()

Takes either file path or ImageInterface. In case of file path, creates an instance of ImageInterface from it.

protected static \Imagine\Image\ImageInterface ensureImageInterfaceInstance ( $image )
$image | string|resource|\Imagine\Image\ImageInterface |
throws | yii\base\InvalidParamException |

Source code

                    protected static function ensureImageInterfaceInstance($image)
    {
        if ($image instanceof ImageInterface) {
            return $image;
        }
        if (is_resource($image)) {
            return static::getImagine()->read($image);
        }
        if (is_string($image)) {
            return static::getImagine()->open(Yii::getAlias($image));
        }
        throw new InvalidParamException('File should be either ImageInterface, resource or a string containing file path.');
    }

frame() public static method

Defined in: yii\imagine\BaseImage::frame()

Adds a frame around of the image. Please note that the image size will increase by `$margin` x 2.

public static \Imagine\Image\ImageInterface frame ( $image, $margin = 20, $color = '666', $alpha = 100 )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$margin | integer | The frame size to add around the image
$color | string | The frame color
$alpha | integer | The alpha value of the frame.

Source code

                    public static function frame($image, $margin = 20, $color = '666', $alpha = 100)
    {
        $img = self::ensureImageInterfaceInstance($image);
        $size = $img->getSize();
        $pasteTo = new Point($margin, $margin);
        $palette = new RGB();
        $color = $palette->color($color, $alpha);
        $box = new Box($size->getWidth() + ceil($margin * 2), $size->getHeight() + ceil($margin * 2));
        $finalImage = static::getImagine()->create($box, $color);
        $finalImage->paste($img, $pasteTo);
        return $finalImage;
    }

getBox() public static method (available since version 2.1.1)

Defined in: yii\imagine\BaseImage::getBox()

Returns box for an image to be created.

If one of the dimensions is set to `null`, another one is calculated automatically based on width to height ratio of original image box.

If both of the dimensions are set then new dimensions are calculated so that image keeps aspect ratio.

You can set $keepAspectRatio to false if you want to force fixed width and height.

public static \Imagine\Image\BoxInterface getBox ( \Imagine\Image\BoxInterface $sourceBox, $width, $height, $keepAspectRatio = true )
$sourceBox | \Imagine\Image\BoxInterface | Original image box
$width | integer | New image width
$height | integer | New image height
$keepAspectRatio | boolean | Should we keep aspect ratio even if both with and height are set
return | \Imagine\Image\BoxInterface | New image box

Source code

                    public static function getBox(BoxInterface $sourceBox, $width, $height, $keepAspectRatio = true)
    {
        if ($width === null && $height === null) {
            throw new InvalidParamException('Width and height cannot be null at same time.');
        }
        $ratio = $sourceBox->getWidth() / $sourceBox->getHeight();
        if ($keepAspectRatio === false) {
            if ($height === null) {
                $height = ceil($width / $ratio);
            } elseif ($width === null) {
                $width = ceil($height * $ratio);
            }
        } else {
            if ($height === null) {
                $height = ceil($width / $ratio);
            } elseif ($width === null) {
                $width = ceil($height * $ratio);
            } elseif ($width / $height > $ratio) {
                $width = $height * $ratio;
            } else {
                $height = $width / $ratio;
            }
        }
        return new Box($width, $height);
    }

getImagine() public static method

Defined in: yii\imagine\BaseImage::getImagine()

Returns the `Imagine` object that supports various image manipulations.

public static \Imagine\Image\ImagineInterface getImagine ( )
return | \Imagine\Image\ImagineInterface | The `Imagine` object

Source code

                    public static function getImagine()
    {
        if (self::$_imagine === null) {
            self::$_imagine = static::createImagine();
        }
        return self::$_imagine;
    }

getThumbnailBox() public static method (available since version 2.0.4)

Defined in: yii\imagine\BaseImage::getThumbnailBox()

Returns box for a thumbnail to be created. If one of the dimensions is set to `null`, another one is calculated automatically based on width to height ratio of original image box.

public static \Imagine\Image\BoxInterface getThumbnailBox ( \Imagine\Image\BoxInterface $sourceBox, $width, $height )
$sourceBox | \Imagine\Image\BoxInterface | Original image box
$width | integer | Thumbnail width
$height | integer | Thumbnail height
return | \Imagine\Image\BoxInterface | Thumbnail box

Source code

                    public static function getThumbnailBox(BoxInterface $sourceBox, $width, $height)
    {
        if ($width !== null && $height !== null) {
            return new Box($width, $height);
        }
        return self::getBox($sourceBox, $width, $height, false);
    }

isUpscaling() public static method

Defined in: yii\imagine\BaseImage::isUpscaling()

Checks if upscaling is going to happen

public static boolean isUpscaling ( \Imagine\Image\BoxInterface $sourceBox, \Imagine\Image\BoxInterface $destinationBox )
$sourceBox | \Imagine\Image\BoxInterface |
$destinationBox | \Imagine\Image\BoxInterface |

Source code

                    public static function isUpscaling(BoxInterface $sourceBox, BoxInterface $destinationBox)
    {
        return ($sourceBox->getWidth() <= $destinationBox->getWidth() && $sourceBox->getHeight() <= $destinationBox->getHeight()) || (!$destinationBox->getWidth() && !$destinationBox->getHeight());
    }

resize() public static method (available since version 2.1.1)

Defined in: yii\imagine\BaseImage::resize()

Resizes an image.

If one of the dimensions is set to `null`, another one is calculated automatically based on aspect ratio of original image.

If both of the dimensions are set then new dimensions are calculated so that image keeps aspect ratio.

You can set $keepAspectRatio to false if you want to force fixed width and height.

public static \Imagine\Image\ImageInterface resize ( $image, $width, $height, $keepAspectRatio = true, $allowUpscaling = false )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$width | integer | The width in pixels
$height | integer | The height in pixels
$keepAspectRatio | boolean | Should the image keep aspect ratio
$allowUpscaling | boolean | Should the image be upscaled if needed

Source code

                    public static function resize($image, $width, $height, $keepAspectRatio = true, $allowUpscaling = false)
    {
        $img = self::ensureImageInterfaceInstance($image)->copy();
        /** @var BoxInterface $sourceBox */
        $sourceBox = $img->getSize();
        $destinationBox = static::getBox($sourceBox, $width, $height, $keepAspectRatio);
        if ($allowUpscaling === false && self::isUpscaling($sourceBox, $destinationBox)) {
            return $img;
        }
        return $img->resize($destinationBox);
    }

setImagine() public static method

Defined in: yii\imagine\BaseImage::setImagine()

public static void setImagine ( $imagine )
$imagine | \Imagine\Image\ImagineInterface | The `Imagine` object.

Source code

                    public static function setImagine($imagine)
    {
        self::$_imagine = $imagine;
    }

text() public static method

Defined in: yii\imagine\BaseImage::text()

Draws a text string on an existing image.

public static \Imagine\Image\ImageInterface text ( $image, $text, $fontFile, array $start = [0, 0], array $fontOptions = [] )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$text | string | The text to write to the image
$fontFile | string | The file path or path alias
$start | array | The starting position of the text. This must be an array with two elements representing `x` and `y` coordinates.

$fontOptions

array

The font options. The following options may be specified:

- color: The font color. Defaults to "fff".
- size: The font size. Defaults to 12.
- angle: The angle to use to write the text. Defaults to 0.

throws | yii\base\InvalidParamException | if `$fontOptions` is invalid

Source code

                    public static function text($image, $text, $fontFile, array $start = [0, 0], array $fontOptions = [])
    {
        if (!isset($start[0], $start[1])) {
            throw new InvalidParamException('$start must be an array of two elements.');
        }
        $fontSize = ArrayHelper::getValue($fontOptions, 'size', 12);
        $fontColor = ArrayHelper::getValue($fontOptions, 'color', 'fff');
        $fontAngle = ArrayHelper::getValue($fontOptions, 'angle', 0);
        $palette = new RGB();
        $color = $palette->color($fontColor);
        $img = self::ensureImageInterfaceInstance($image);
        $font = static::getImagine()->font(Yii::getAlias($fontFile), $fontSize, $color);
        $img->draw()->text($text, $font, new Point($start[0], $start[1]), $fontAngle);
        return $img;
    }

thumbnail() public static method

Defined in: yii\imagine\BaseImage::thumbnail()

Creates a thumbnail image.

If one of thumbnail dimensions is set to `null`, another one is calculated automatically based on aspect ratio of original image. Note that calculated thumbnail dimension may vary depending on the source image in this case.

If both dimensions are specified, resulting thumbnail would be exactly the width and height specified. How it's achieved depends on the mode defined via settings parameter.

If `ImageInterface::THUMBNAIL_OUTBOUND` mode is used, which is default, then the thumbnail is scaled so that its smallest side equals the length of the corresponding side in the original image. Any excess outside of the scaled thumbnail’s area will be cropped, and the returned thumbnail will have the exact width and height specified.

If thumbnail mode is `ImageInterface::THUMBNAIL_INSET`, the original image is scaled down so it is fully contained within the thumbnail dimensions. The rest is filled with background that could be configured via yii\imagine\Image::$thumbnailBackgroundColor and yii\imagine\Image::$thumbnailBackgroundAlpha.

public static \Imagine\Image\ImageInterface thumbnail ( $image, $width, $height, $settings = ManipulatorInterface::THUMBNAIL_OUTBOUND )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$width | integer | The width in pixels to create the thumbnail
$height | integer | The height in pixels to create the thumbnail
$settings | integer | Settings for resizing original image, one or more of the ManipulatorInterface::THUMBNAIL_ flags (joined with |)

Source code

                    public static function thumbnail($image, $width, $height, $settings = ManipulatorInterface::THUMBNAIL_OUTBOUND)
    {
        $img = self::ensureImageInterfaceInstance($image);
        /** @var BoxInterface $sourceBox */
        $sourceBox = $img->getSize();
        $thumbnailBox = static::getThumbnailBox($sourceBox, $width, $height);
        $allowUpscale = (bool) ($settings & ImageInterface::THUMBNAIL_FLAG_UPSCALE);
        if (self::isUpscaling($sourceBox, $thumbnailBox) && !$allowUpscale) {
            return $img->copy();
        }
        $img = $img->thumbnail($thumbnailBox, $settings);
        if ($settings & ImageInterface::THUMBNAIL_OUTBOUND) {
            return $img;
        }
        $size = $img->getSize();
        if ($size->getWidth() == $width && $size->getHeight() == $height) {
            return $img;
        }
        $palette = new RGB();
        $color = $palette->color(static::$thumbnailBackgroundColor, static::$thumbnailBackgroundAlpha);
        // create empty image to preserve aspect ratio of thumbnail
        $thumb = static::getImagine()->create($thumbnailBox, $color);
        // calculate points
        $startX = 0;
        $startY = 0;
        if ($size->getWidth() < $width) {
            $startX = ceil(($width - $size->getWidth()) / 2);
        }
        if ($size->getHeight() < $height) {
            $startY = ceil(($height - $size->getHeight()) / 2);
        }
        $thumb->paste($img, new Point($startX, $startY));
        return $thumb;
    }

watermark() public static method

Defined in: yii\imagine\BaseImage::watermark()

Adds a watermark to an existing image.

public static \Imagine\Image\ImageInterface watermark ( $image, $watermarkImage, array $start = [0, 0] )
$image | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing file path
$watermarkImage | string|resource|\Imagine\Image\ImageInterface | Either ImageInterface, resource or a string containing watermark file path
$start | array | The starting point. This must be an array with two elements representing `x` and `y` coordinates.
throws | yii\base\InvalidParamException | if `$start` is invalid

Source code

                    public static function watermark($image, $watermarkImage, array $start = [0, 0])
    {
        if (!isset($start[0], $start[1])) {
            throw new InvalidParamException('$start must be an array of two elements.');
        }
        $img = self::ensureImageInterfaceInstance($image);
        $watermark = self::ensureImageInterfaceInstance($watermarkImage);
        $img->paste($watermark, new Point($start[0], $start[1]));
        return $img;
    }