ImageMagickHandler
extends BaseHandler
in package
Class ImageMagickHandler
To make this library as compatible as possible with the broadest number of installations, we do not use the Imagick extension, but simply use the command line version.
hmm - the width & height accessors at the end use the imagick extension.
FIXME - This needs conversion & unit testing, to use the imagick extension
Table of Contents
- $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.
- __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.
- _flatten() : $this
- Flattens transparencies, default white background
- _flip() : $this
- Flips an image along it's vertical or horizontal axis.
- _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.
- _rotate() : $this
- Handles the rotation of an image resource.
- _text() : mixed
- 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() : mixed
- 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() : mixed
- Check if given image format is supported
Properties
$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
Methods
__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> = []
Return values
mixed —__construct()
Constructor.
public
__construct([Images $config = null ]) : mixed
Parameters
- $config : Images = null
Tags
Return values
mixed —_crop()
Crops the image.
public
_crop() : bool|ImageMagickHandler
Tags
Return values
bool|ImageMagickHandler —_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
Tags
Return values
$this —_flip()
Flips an image along it's vertical or horizontal axis.
public
_flip(string $direction) : $this
Parameters
- $direction : string
Tags
Return values
$this —_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
Tags
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 $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
- $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.
Tags
Return values
mixed —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([string|null $target = null ][, int $quality = 90 ]) : bool
Example: $image->resize(100, 200, true) ->save();
Parameters
- $target : 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 —_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
Tags
Return values
$this —_text()
Handler-specific method for overlaying text on an image.
protected
_text(string $text[, array<string|int, mixed> $options = [] ]) : mixed
Parameters
- $text : string
- $options : array<string|int, mixed> = []
Tags
Return values
mixed —calcAspectRatio()
Calculate image aspect ratio.
protected
calcAspectRatio(int|float $width[, int|float|null $height = null ], int|float $origWidth, int|float $origHeight) : array<string|int, mixed>
Parameters
- $width : int|float
- $height : int|float|null = null
- $origWidth : int|float
- $origHeight : int|float
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(int|float $width, int|float $height, int|float $origWidth, int|float $origHeight, string $position) : array<string|int, mixed>
Parameters
- $width : int|float
- $height : int|float
- $origWidth : int|float
- $origHeight : int|float
- $position : string
Return values
array<string|int, mixed> —ensureResource()
Make the image resource object if needed
protected
ensureResource() : mixed
Tags
Return values
mixed —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.
Tags
Return values
string —image()
Verifies that a file has been supplied and it is an image.
protected
image() : Image
Tags
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
Tags
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.
Return values
void —supportedFormatCheck()
Check if given image format is supported
protected
supportedFormatCheck() : mixed