CodeIgniter v4.5 API

GDHandler extends BaseHandler
in package

Application

Image handler for GD package

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 : resource|null: Temporary image used by the different engines.
$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() : GDHandler: Crops the image.
_getHeight() : int: Return image height.
_getWidth() : int: Return image width.
_resize() : GDHandler: Resizes 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() : mixed: Get GD 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
_flip() : $this: Flips an image along it's vertical or horizontal axis.
_rotate() : mixed: Handles the rotation of an image resource.
_text() : void: Add text overlay to 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.
createImage() : bool|resource: Create Image Resource
ensureResource() : void: Make the image resource object if needed
getImageResource() : bool|resource: Check if image type is supported and return image resource
image() : Image: Verifies that a file has been supplied and it is an image.
process() : $this: Handles all of the grunt work of resizing, etc.
reproportion() : void: Re-proportion Image Width/Height
textOverlay() : mixed: Handler-specific method for overlaying text on an image.

$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

Temporary image used by the different engines.


    protected
        resource|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|null $config = null ]) : mixed

Parameters

$config : Images|null = null

_crop()

Crops the image.


    public
                    _crop() : GDHandler

Return values

GDHandler

_getHeight()

Return image height.


    public
                    _getHeight() : int

Return values

int

_getWidth()

Return image width.


    public
                    _getWidth() : int

Return values

int

_resize()

Resizes the image.


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

Parameters

$maintainRatio : bool = false

Return values

GDHandler

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 GD version


    public
                    getVersion() : mixed

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


    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) : mixed

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

Parameters

$angle : int

_text()

Add text overlay to 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>

createImage()

Create Image Resource


    protected
                    createImage([string $path = '' ][, string $imageType = '' ]) : bool|resource

This simply creates an image resource handle based on the type of image being processed

Parameters

$path : string = ''
$imageType : string = ''

Return values

bool|resource

ensureResource()

Make the image resource object if needed


    protected
                    ensureResource() : void

getImageResource()

Check if image type is supported and return image resource


    protected
                    getImageResource(string $path, int $imageType) : bool|resource

Parameters

$path : string: Image path
$imageType : int: Image type

Return values

bool|resource

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) : $this

Parameters

$action : string

Return values

$this

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.

textOverlay()

Handler-specific method for overlaying text on an image.


    protected
                    textOverlay(string $text[, array<string|int, mixed> $options = [] ][, bool $isShadow = false ]) : mixed

Parameters

$text : string
$options : array<string|int, mixed> = []
$isShadow : bool = false: Whether we are drawing the dropshadow or actual text

GDHandler 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()

Return values

_getHeight()

Return values

_getWidth()

Return values

_resize()

Parameters

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()

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

withResource()

Return values

_flatten()

GDHandler extends BaseHandler
in package

Application