HumHub Documentation (unofficial)

Image extends BaseImage
in package

Image implements most commonly used image manipulation functions using the [Imagine library](http://imagine.readthedocs.org/).

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]);
Tags
author

Antonio Ramirez amigo.cobos@gmail.com

author

Qiang Xue qiang.xue@gmail.com

since
2.0

Table of Contents

Constants

DRIVER_GD2  = 'gd2'
GD2 driver definition for Imagine implementation using the GD library.
DRIVER_GMAGICK  = 'gmagick'
gmagick driver definition.
DRIVER_IMAGICK  = 'imagick'
imagick driver definition.

Properties

$driver  : array<string|int, mixed>|string
$thumbnailBackgroundAlpha  : string
$thumbnailBackgroundColor  : string
$_imagine  : ImagineInterface

Methods

autorotate()  : ImageInterface
Rotates an image automatically based on EXIF information.
crop()  : ImageInterface
Crops an image.
frame()  : ImageInterface
Adds a frame around of the image. Please note that the image size will increase by `$margin` x 2.
getBox()  : BoxInterface
Returns box for an image to be created.
getImagine()  : ImagineInterface
Returns the `Imagine` object that supports various image manipulations.
getThumbnailBox()  : BoxInterface
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.
isUpscaling()  : bool
Checks if upscaling is going to happen
resize()  : ImageInterface
Resizes an image.
setImagine()  : mixed
text()  : ImageInterface
Draws a text string on an existing image.
thumbnail()  : ImageInterface
Creates a thumbnail image.
watermark()  : ImageInterface
Adds a watermark to an existing image.
createImagine()  : ImagineInterface
Creates an `Imagine` object based on the specified [[driver]].
ensureImageInterfaceInstance()  : ImageInterface
Takes either file path or ImageInterface. In case of file path, creates an instance of ImageInterface from it.

Constants

DRIVER_GD2

GD2 driver definition for Imagine implementation using the GD library.

public mixed DRIVER_GD2 = 'gd2'

DRIVER_GMAGICK

gmagick driver definition.

public mixed DRIVER_GMAGICK = 'gmagick'

DRIVER_IMAGICK

imagick driver definition.

public mixed DRIVER_IMAGICK = 'imagick'

Properties

$driver

public static array<string|int, mixed>|string $driver = [self::DRIVER_GMAGICK, self::DRIVER_IMAGICK, self::DRIVER_GD2]

the driver to use. This can be either a single driver name or an array of driver names. If the latter, the first available driver will be used.

$thumbnailBackgroundAlpha

public static string $thumbnailBackgroundAlpha = 100

background alpha (transparency) to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET mode with both width and height specified. Default is solid.

Tags
since
2.0.4

$thumbnailBackgroundColor

public static string $thumbnailBackgroundColor = 'FFF'

background color to use when creating thumbnails in ImageInterface::THUMBNAIL_INSET mode with both width and height specified. Default is white.

Tags
since
2.0.4

Methods

autorotate()

Rotates an image automatically based on EXIF information.

public static autorotate(string|resource|ImageInterface $image[, string $color = '000000' ]) : ImageInterface
Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$color : string = '000000'
Tags
since
2.1.0
Return values
ImageInterface

crop()

Crops an image.

public static crop(string|resource|ImageInterface $image, int $width, int $height[, array<string|int, mixed> $start = [0, 0] ]) : ImageInterface

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);
Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$width : int

the crop width

$height : int

the crop height

$start : array<string|int, mixed> = [0, 0]

the starting point. This must be an array with two elements representing x and y coordinates.

Tags
throws
InvalidParamException

if the $start parameter is invalid

Return values
ImageInterface

frame()

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

public static frame(string|resource|ImageInterface $image[, int $margin = 20 ][, string $color = '666' ][, int $alpha = 100 ]) : ImageInterface
Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$margin : int = 20

the frame size to add around the image

$color : string = '666'

the frame color

$alpha : int = 100

the alpha value of the frame.

Return values
ImageInterface

getBox()

Returns box for an image to be created.

public static getBox(BoxInterface $sourceBox, int $width, int $height[, bool $keepAspectRatio = true ]) : BoxInterface

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.

Parameters
$sourceBox : BoxInterface

original image box

$width : int

new image width

$height : int

new image height

$keepAspectRatio : bool = true

should we keep aspect ratio even if both with and height are set

Tags
since
2.1.1
Return values
BoxInterface —

new image box

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 getThumbnailBox(BoxInterface $sourceBox, int $width, int $height) : BoxInterface
Parameters
$sourceBox : BoxInterface

original image box

$width : int

thumbnail width

$height : int

thumbnail height

Tags
since
2.0.4
Return values
BoxInterface —

thumbnail box

resize()

Resizes an image.

public static resize(string|resource|ImageInterface $image, int $width, int $height[, bool $keepAspectRatio = true ][, bool $allowUpscaling = false ]) : ImageInterface

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.

Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$width : int

the width in pixels

$height : int

the height in pixels

$keepAspectRatio : bool = true

should the image keep aspect ratio

$allowUpscaling : bool = false

should the image be upscaled if needed

Tags
since
2.1.1
Return values
ImageInterface

text()

Draws a text string on an existing image.

public static text(string|resource|ImageInterface $image, string $text, string $fontFile[, array<string|int, mixed> $start = [0, 0] ][, array<string|int, mixed> $fontOptions = [] ]) : ImageInterface
Parameters
$image : string|resource|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<string|int, mixed> = [0, 0]

the starting position of the text. This must be an array with two elements representing x and y coordinates.

$fontOptions : array<string|int, mixed> = []

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.
Tags
throws
InvalidParamException

if $fontOptions is invalid

Return values
ImageInterface

thumbnail()

Creates a thumbnail image.

public static thumbnail(string|resource|ImageInterface $image, int $width, int $height[, int $settings = ManipulatorInterface::THUMBNAIL_OUTBOUND ]) : ImageInterface

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 [[Image::$thumbnailBackgroundColor]] and [[Image::$thumbnailBackgroundAlpha]].

Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$width : int

the width in pixels to create the thumbnail

$height : int

the height in pixels to create the thumbnail

$settings : int = ManipulatorInterface::THUMBNAIL_OUTBOUND

settings for resizing original image, one or more of the ManipulatorInterface::THUMBNAIL_ flags (joined with |)

Return values
ImageInterface

watermark()

Adds a watermark to an existing image.

public static watermark(string|resource|ImageInterface $image, string|resource|ImageInterface $watermarkImage[, array<string|int, mixed> $start = [0, 0] ]) : ImageInterface
Parameters
$image : string|resource|ImageInterface

either ImageInterface, resource or a string containing file path

$watermarkImage : string|resource|ImageInterface

either ImageInterface, resource or a string containing watermark file path

$start : array<string|int, mixed> = [0, 0]

the starting point. This must be an array with two elements representing x and y coordinates.

Tags
throws
InvalidParamException

if $start is invalid

Return values
ImageInterface 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results