CodeIgniter v4.5 API

ImageMagickHandler extends BaseHandler
in package

Application

Class ImageMagickHandler

FIXME - This needs conversion & unit testing, to use the imagick extension

Properties

$config : Images: Configuration settings.
$filePermissions : int: File permission mask.
$height : int: Image height.
$image : Image: The image/file instance
$masterDim : string: Master dimensioning.
$resource : string|null: Stores image resource in memory.
$supportTransparency : array<string|int, mixed>: Image types with support for transparency.
$textDefaults : array<string|int, mixed>: Default options for text watermarking.
$verified : bool: Whether the image file has been confirmed.
$width : int: Image width.
$xAxis : int|null: X-axis.
$yAxis : int|null: Y-axis.

Methods

__call() : mixed: Provide access to the Image class' methods if they don't exist on the handler itself.
__construct() : mixed: Constructor.
_crop() : bool|ImageMagickHandler: Crops the image.
_getHeight() : int: Return the height of an image.
_getWidth() : int: Return the width of an image.
_resize() : ImageMagickHandler: Handles the actual resizing of the image.
convert() : $this: Changes the stored image type to indicate the new file format to use when saving.
crop() : $this: Crops the image to the desired height and width. If one of the height/width values is not provided, that value will be set the appropriate value based on offsets and image dimensions.
fit() : BaseHandler: Combine cropping and resizing into a single command.
flatten() : $this: Flattens transparencies, default white background
flip() : $this: Flips an image either horizontally or vertically.
getEXIF() : mixed: Retrieve the EXIF information from the image, if possible. Returns an array of the information, or null if nothing can be found.
getFile() : Image: Returns the image instance.
getHeight() : int: Return image height.
getResource() : resource: Returns the temporary image used during the image processing.
getVersion() : string: Get driver version
getWidth() : int: Return image width.
reorient() : $this: Reads the EXIF information from the image and modifies the orientation so that displays correctly in the browser. This is especially an issue with images taken by smartphones who always store the image up-right, but set the orientation flag to display it correctly.
resize() : BaseHandler: Resize the image
rotate() : $this: Rotates the image on the current canvas.
save() : bool: Saves any changes that have been made to file. If no new filename is provided, the existing image is overwritten, otherwise a copy of the file is made at $target.
text() : $this: Overlays a string of text over the image.
withFile() : $this: Sets another image for this handler to work on.
withResource() : $this: Load the temporary image used during the image processing.
_flatten() : $this: Flattens transparencies, default white background
_flip() : $this: Flips an image along it's vertical or horizontal axis.
_rotate() : $this: Handles the rotation of an image resource.
_text() : void: Handler-specific method for overlaying text on an image.
calcAspectRatio() : array<string|int, mixed>: Calculate image aspect ratio.
calcCropCoords() : array<string|int, mixed>: Based on the position, will determine the correct x/y coords to crop the desired portion from the image.
ensureResource() : void: Make the image resource object if needed
getResourcePath() : string: Get Image Resource
image() : Image: Verifies that a file has been supplied and it is an image.
process() : array<string|int, mixed>: Handles all of the grunt work of resizing, etc.
reproportion() : void: Re-proportion Image Width/Height
supportedFormatCheck() : void: Check if given image format is supported

$config

Configuration settings.


    protected
        Images
    $config

$filePermissions

File permission mask.


    protected
        int
    $filePermissions
     = 0644

$height

Image height.


    protected
        int
    $height
     = 0

$image

The image/file instance


    protected
        Image
    $image

$masterDim

Master dimensioning.


    protected
        string
    $masterDim
     = 'auto'

$resource

Stores image resource in memory.


    protected
        string|null
    $resource

$supportTransparency

Image types with support for transparency.


    protected
        array<string|int, mixed>
    $supportTransparency
     = [IMAGETYPE_PNG, IMAGETYPE_WEBP]

$textDefaults

Default options for text watermarking.


    protected
        array<string|int, mixed>
    $textDefaults
     = ['fontPath' => null, 'fontSize' => 16, 'color' => 'ffffff', 'opacity' => 1.0, 'vAlign' => 'bottom', 'hAlign' => 'center', 'vOffset' => 0, 'hOffset' => 0, 'padding' => 0, 'withShadow' => false, 'shadowColor' => '000000', 'shadowOffset' => 3]

$verified

Whether the image file has been confirmed.


    protected
        bool
    $verified
     = false

$width

Image width.


    protected
        int
    $width
     = 0

$xAxis

X-axis.


    protected
        int|null
    $xAxis
     = 0

$yAxis

Y-axis.


    protected
        int|null
    $yAxis
     = 0

__call()

Provide access to the Image class' methods if they don't exist on the handler itself.


    public
                    __call(string $name[, array<string|int, mixed> $args = [] ]) : mixed

Parameters

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

__construct()

Constructor.


    public
                    __construct([Images $config = null ]) : mixed

Parameters

$config : Images = null

_crop()

Crops the image.


    public
                    _crop() : bool|ImageMagickHandler

Return values

bool|ImageMagickHandler

_getHeight()

Return the height of an image.


    public
                    _getHeight() : int

Return values

int

_getWidth()

Return the width of an image.


    public
                    _getWidth() : int

Return values

int

_resize()

Handles the actual resizing of the image.


    public
                    _resize([bool $maintainRatio = false ]) : ImageMagickHandler

Parameters

$maintainRatio : bool = false

Return values

ImageMagickHandler

convert()

Changes the stored image type to indicate the new file format to use when saving.


    public
                    convert(int $imageType) : $this

Does not touch the actual resource.

Parameters

$imageType : int: A PHP imageType constant, e.g. https://www.php.net/manual/en/function.image-type-to-mime-type.php

Return values

$this

crop()

Crops the image to the desired height and width. If one of the height/width values is not provided, that value will be set the appropriate value based on offsets and image dimensions.


    public
                    crop([int|null $width = null ][, int|null $height = null ][, int|null $x = null ][, int|null $y = null ][, bool $maintainRatio = false ][, string $masterDim = 'auto' ]) : $this

Parameters

$width : int|null = null
$height : int|null = null
$x : int|null = null: X-axis coord to start cropping from the left of image
$y : int|null = null: Y-axis coord to start cropping from the top of image
$maintainRatio : bool = false
$masterDim : string = 'auto'

Return values

$this

fit()

Combine cropping and resizing into a single command.


    public
                    fit(int $width[, int|null $height = null ][, string $position = 'center' ]) : BaseHandler

Supported positions:

top-left
top
top-right
left
center
right
bottom-left
bottom
bottom-right

Parameters

$width : int
$height : int|null = null
$position : string = 'center'

Return values

BaseHandler

flatten()

Flattens transparencies, default white background


    public
                    flatten([int $red = 255 ][, int $green = 255 ][, int $blue = 255 ]) : $this

Parameters

$red : int = 255
$green : int = 255
$blue : int = 255

Return values

$this

flip()

Flips an image either horizontally or vertically.


    public
                    flip([string $dir = 'vertical' ]) : $this

Parameters

$dir : string = 'vertical': Either 'vertical' or 'horizontal'

Return values

$this

getEXIF()

Retrieve the EXIF information from the image, if possible. Returns an array of the information, or null if nothing can be found.


    public
                    getEXIF([string|null $key = null ][, bool $silent = false ]) : mixed

EXIF data is only supported fr JPEG & TIFF formats.

Parameters

$key : string|null = null: If specified, will only return this piece of EXIF data.
$silent : bool = false: If true, will not throw our own exceptions.

getFile()

Returns the image instance.


    public
                    getFile() : Image

Return values

Image

getHeight()

Return image height.


    public
                    getHeight() : int

accessor for testing; not part of interface

Return values

int

getResource()

Returns the temporary image used during the image processing.


    public
                    getResource() : resource

Good for extending the system or doing things this library is not intended to do.

Return values

resource

getVersion()

Get driver version


    public
                    getVersion() : string

Return values

string

getWidth()

Return image width.


    public
                    getWidth() : int

accessor for testing; not part of interface

Return values

int

reorient()

Reads the EXIF information from the image and modifies the orientation so that displays correctly in the browser. This is especially an issue with images taken by smartphones who always store the image up-right, but set the orientation flag to display it correctly.


    public
                    reorient([bool $silent = false ]) : $this

Parameters

$silent : bool = false: If true, will ignore exceptions when PHP doesn't support EXIF.

Return values

$this

resize()

Resize the image


    public
                    resize(int $width, int $height[, bool $maintainRatio = false ][, string $masterDim = 'auto' ]) : BaseHandler

Parameters

$width : int
$height : int
$maintainRatio : bool = false: If true, will get the closest match possible while keeping aspect ratio true.
$masterDim : string = 'auto'

Return values

BaseHandler

rotate()

Rotates the image on the current canvas.


    public
                    rotate(float $angle) : $this

Parameters

$angle : float

Return values

$this

save()

Saves any changes that have been made to file. If no new filename is provided, the existing image is overwritten, otherwise a copy of the file is made at $target.


    public
                    save([non-empty-string|null $target = null ][, int $quality = 90 ]) : bool

Example: $image->resize(100, 200, true) ->save();

Parameters

$target : non-empty-string|null = null
$quality : int = 90

Return values

bool

text()

Overlays a string of text over the image.


    public
                    text(string $text[, array<string|int, mixed> $options = [] ]) : $this

Valid options:

color Text Color (hex number)
shadowColor Color of the shadow (hex number)
hAlign Horizontal alignment: left, center, right
vAlign Vertical alignment: top, middle, bottom
hOffset
vOffset
fontPath
fontSize
shadowOffset

Parameters

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

Return values

$this

withFile()

Sets another image for this handler to work on.


    public
                    withFile(string $path) : $this

Keeps us from needing to continually instantiate the handler.

Parameters

$path : string

Return values

$this

withResource()

Load the temporary image used during the image processing.


    public
                    withResource() : $this

Some functions e.g. save() will only copy and not compress your image otherwise.

Return values

$this

_flatten()

Flattens transparencies, default white background


    protected
                    _flatten([int $red = 255 ][, int $green = 255 ][, int $blue = 255 ]) : $this

Parameters

$red : int = 255
$green : int = 255
$blue : int = 255

Return values

$this

_flip()

Flips an image along it's vertical or horizontal axis.


    protected
                    _flip(string $direction) : $this

Parameters

$direction : string

Return values

$this

_rotate()

Handles the rotation of an image resource.


    protected
                    _rotate(int $angle) : $this

Doesn't save the image, but replaces the current resource.

Parameters

$angle : int

Return values

$this

_text()

Handler-specific method for overlaying text on an image.


    protected
                    _text(string $text[, array<string|int, mixed> $options = [] ]) : void

Parameters

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

calcAspectRatio()

Calculate image aspect ratio.


    protected
                    calcAspectRatio(float|int $width[, float|int|null $height = null ][, float|int $origWidth = 0 ][, float|int $origHeight = 0 ]) : array<string|int, mixed>

Parameters

$width : float|int
$height : float|int|null = null
$origWidth : float|int = 0
$origHeight : float|int = 0

Return values

array<string|int, mixed>

calcCropCoords()

Based on the position, will determine the correct x/y coords to crop the desired portion from the image.


    protected
                    calcCropCoords(float|int $width, float|int $height, float|int $origWidth, float|int $origHeight, string $position) : array<string|int, mixed>

Parameters

$width : float|int
$height : float|int
$origWidth : float|int
$origHeight : float|int
$position : string

Return values

array<string|int, mixed>

ensureResource()

Make the image resource object if needed


    protected
                    ensureResource() : void

getResourcePath()

Get Image Resource


    protected
                    getResourcePath() : string

This simply creates an image resource handle based on the type of image being processed. Since ImageMagick is used on the cli, we need to ensure we have a temporary file on the server that we can use.

To ensure we can use all features, like transparency, during the process, we'll use a PNG as the temp file type.

Return values

string

image()

Verifies that a file has been supplied and it is an image.


    protected
                    image() : Image

Return values

Image —

The image instance

process()

Handles all of the grunt work of resizing, etc.


    protected
                    process(string $action[, int $quality = 100 ]) : array<string|int, mixed>

Parameters

$action : string
$quality : int = 100

Return values

array<string|int, mixed> —

Lines of output from shell command

reproportion()

Re-proportion Image Width/Height


    protected
                    reproportion() : void

When creating thumbs, the desired width/height can end up warping the image due to an incorrect ratio between the full-sized image and the thumb.

This function lets us re-proportion the width/height if users choose to maintain the aspect ratio when resizing.

supportedFormatCheck()

Check if given image format is supported


    protected
                    supportedFormatCheck() : void

ImageMagickHandler extends BaseHandler in package Application

Table of Contents

Properties

Methods

Properties

$config

$filePermissions

$height

$image

$masterDim

$resource

$supportTransparency

$textDefaults

$verified

$width

$xAxis

$yAxis

Methods

__call()

Parameters

__construct()

Parameters

Tags

_crop()

Tags

Return values

_getHeight()

Return values

_getWidth()

Return values

_resize()

Parameters

Tags

Return values

convert()

Parameters

Return values

crop()

Parameters

Return values

fit()

Parameters

Return values

flatten()

Parameters

Return values

flip()

Parameters

Return values

getEXIF()

Parameters

Tags

getFile()

Return values

getHeight()

Return values

getResource()

Return values

getVersion()

Return values

getWidth()

Return values

reorient()

Parameters

Return values

resize()

Parameters

Return values

rotate()

Parameters

Return values

save()

Parameters

Return values

text()

Parameters

Return values

withFile()

Parameters

Return values

ImageMagickHandler extends BaseHandler
in package

Application