Image

Class to manipulate an image.

since

1.7.3

package

Joomla CMS

Methods

__construct

Class constructor.

__construct( source = null) : 
since

1.7.3

throws

RuntimeException

Arguments

source

mixedEither a file path for a source image or a GD resource handler for an image.

Response

mixed

__destruct

Method to call the destroy() method one last time to free any memory when the object is unset

__destruct() : 
see Image::destroy()
since

2.5.0

Response

mixed

createThumbnails

Method to create thumbnails from the current image and save them to disk. It allows creation by resizing or cropping the original image.

createThumbnails( thumbSizes,  creationMethod = self::SCALE_INSIDE,  thumbsFolder = null,  useOriginalName = false) : mixed||string|int
since

4.3.0

throws

LogicException

InvalidArgumentException

Arguments

thumbSizes

mixedstring or array of strings. Example: $thumbSizes = ['150x75','250x150'];

creationMethod

int1-3 resize $scaleMethod | 4 create cropping

thumbsFolder

stringdestination thumbs folder. null generates a thumbs folder in the image folder

useOriginalName

boolShall we use the original image name? Defaults is false, {filename}_{width}x{height}.{ext}

Response

array<string|int, mixed>

createThumbs

Method to create thumbnails from the current image and save them to disk. It allows creation by resizing or cropping the original image.

createThumbs( thumbSizes,  creationMethod = self::SCALE_INSIDE,  thumbsFolder = null) : mixed||string|int
deprecated
since

2.5.0

throws

LogicException

InvalidArgumentException

deprecated

4.0 will be removed in 6.0 Use \Joomla\CMS\Image\createThumbnails instead

Arguments

thumbSizes

mixedstring or array of strings. Example: $thumbSizes = ['150x75','250x150'];

creationMethod

int1-3 resize $scaleMethod | 4 create cropping

thumbsFolder

stringdestination thumbs folder. null generates a thumbs folder in the image folder

Response

array<string|int, mixed>

crop

Method to crop the current image.

crop( width,  height,  left = null,  top = null,  createNew = true) : \Joomla\CMS\Image\Image
since

2.5.0

throws

LogicException

Arguments

width

mixedThe width of the image section to crop in pixels or a percentage.

height

mixedThe height of the image section to crop in pixels or a percentage.

left

intThe number of pixels from the left to start cropping.

top

intThe number of pixels from the top to start cropping.

createNew

boolIf true the current image will be cloned, cropped and returned; else the current image will be cropped and returned.

Response

Image

cropResize

Method to crop an image after resizing it to maintain proportions without having to do all the set up work.

cropResize( width,  height,  createNew = true) : \Joomla\CMS\Image\Image
since

2.5.0

Arguments

width

intThe desired width of the image in pixels or a percentage.

height

intThe desired height of the image in pixels or a percentage.

createNew

boolIf true the current image will be cloned, resized, cropped and returned.

Response

Image

destroy

Method to destroy an image handle and free the memory associated with the handle

destroy() : 
since

2.5.0

Response

boolTrue on success, false on failure or if no image is loaded

filter

Method to apply a filter to the image by type. Two examples are: grayscale and sketchy.

filter( type, mixed||string|int options = []) : \Joomla\CMS\Image\Image
since

2.5.0

see Filter
throws

LogicException

Arguments

type

stringThe name of the image filter to apply.

options

array<string|int, mixed>An array of options for the filter.

Response

Image

flip

Method to flip the current image.

flip( mode,  createNew = true) : \Joomla\CMS\Image\Image
since

3.4.2

throws

LogicException

Arguments

mode

intThe flip mode for flipping the image {@link http://php.net/imageflip#refsect1-function.imageflip-parameters}

createNew

boolIf true the current image will be cloned, flipped and returned; else the current image will be flipped and returned.

Response

Image

generateThumbs

Method to generate thumbnails from the current image. It allows creation by resizing or cropping the original image.

generateThumbs( thumbSizes,  creationMethod = self::SCALE_INSIDE) : mixed||string|int
since

2.5.0

throws

LogicException

InvalidArgumentException

Arguments

thumbSizes

mixedString or array of strings. Example: $thumbSizes = array('150x75','250x150');

creationMethod

int1-3 resize $scaleMethod | 4 create cropping | 5 resize then crop

Response

array<string|int, mixed>

getFilterInstance

Method to get an image filter instance of a specified type.

getFilterInstance( type) : \Joomla\CMS\Image\ImageFilter
since

2.5.0

throws

RuntimeException

Arguments

type

stringThe image filter type to get.

Response

ImageFilter

getHandle

Get the image resource handle

getHandle() : 
since

3.8.0

throws

LogicExceptionif an image has not been loaded into the instance

Response

resource

getHeight

Method to get the height of the image in pixels.

getHeight() : 
since

2.5.0

throws

LogicException

Response

int

getImageFileProperties

Method to return a properties object for an image given a filesystem path.

getImageFileProperties( path) : \stdClass
static

The result object has values for image width, height, type, attributes, mime type, bits, and channels.

since

2.5.0

throws

InvalidArgumentException

RuntimeException

Arguments

path

stringThe filesystem path to the image for which to get properties.

Response

stdClass

getOrientation

Method to detect whether an image's orientation is landscape, portrait or square.

getOrientation() : 

The orientation will be returned as a string.

since

3.4.2

Response

mixedOrientation string or null.

getOrientationString

Compare width and height integers to determine image orientation.

getOrientationString( width,  height) : 
static
since

3.4.2

Arguments

width

intThe width value to use for calculation

height

intThe height value to use for calculation

Response

stringOrientation string

getPath

Method to return the path

getPath() : 
since

2.5.0

Response

string

getWidth

Method to get the width of the image in pixels.

getWidth() : 
since

2.5.0

throws

LogicException

Response

int

isLoaded

Method to determine whether or not an image has been loaded into the object.

isLoaded() : 
since

2.5.0

Response

bool

isTransparent

Method to determine whether or not the image has transparency.

isTransparent() : 
since

2.5.0

throws

LogicException

Response

bool

loadFile

Method to load a file into the Image object as the resource.

loadFile( path) : 
since

2.5.0

throws

InvalidArgumentException

RuntimeException

Arguments

path

stringThe filesystem path to load as an image.

Response

void

prepareDimensions

Method to get the new dimensions for a resized image.

prepareDimensions( width,  height,  scaleMethod) : \stdClass
since

2.5.0

throws

InvalidArgumentExceptionIf width, height or both given as zero

Arguments

width

intThe width of the resized image in pixels.

height

intThe height of the resized image in pixels.

scaleMethod

intThe method to use for scaling

Response

stdClass

resize

Method to resize the current image.

resize( width,  height,  createNew = true,  scaleMethod = self::SCALE_INSIDE) : \Joomla\CMS\Image\Image
since

2.5.0

throws

LogicException

Arguments

width

mixedThe width of the resized image in pixels or a percentage.

height

mixedThe height of the resized image in pixels or a percentage.

createNew

boolIf true the current image will be cloned, resized and returned; else the current image will be resized and returned.

scaleMethod

intWhich method to use for scaling

Response

Image

rotate

Method to rotate the current image.

rotate( angle,  background = -1,  createNew = true) : \Joomla\CMS\Image\Image
since

2.5.0

throws

LogicException

Arguments

angle

mixedThe angle of rotation for the image

background

intThe background color to use when areas are added due to rotation

createNew

boolIf true the current image will be cloned, rotated and returned; else the current image will be rotated and returned.

Response

Image

sanitizeHeight

Method to sanitize a height value.

sanitizeHeight( height,  width) : 
since

2.5.0

Arguments

height

mixedThe input height value to sanitize.

width

mixedThe input width value for reference.

Response

int

sanitizeOffset

Method to sanitize an offset value like left or top.

sanitizeOffset( offset) : 
since

2.5.0

Arguments

offset

mixedAn offset value.

Response

int

sanitizeWidth

Method to sanitize a width value.

sanitizeWidth( width,  height) : 
since

2.5.0

Arguments

width

mixedThe input width value to sanitize.

height

mixedThe input height value for reference.

Response

int

setThumbnailGenerate

Method for set option of generate thumbnail method

setThumbnailGenerate( quality = true) : 
since

3.7.0

Arguments

quality

boolTrue for best quality. False for best speed.

Response

void

toFile

Method to write the current image out to a file or output directly.

toFile( path,  type = IMAGETYPE_JPEG, mixed||string|int options = []) : 
link
since

2.5.0

throws

LogicException

Arguments

path

mixedThe filesystem path to save the image. When null, the raw image stream will be outputted directly.

type

intThe image type to save the file as.

options

array<string|int, mixed>The image type options to use in saving the file. For PNG and JPEG formats use quality key to set compression level (0..9 and 0..100)

Response

bool

watermark

Watermark the image

watermark(\Joomla\CMS\Image\Image watermark,  transparency = 50,  bottomMargin,  rightMargin) : \Joomla\CMS\Image\Image
since

3.8.0

link

Arguments

watermark

ImageThe Image object containing the watermark graphic

transparency

intThe transparency to use for the watermark graphic

bottomMargin

intThe margin from the bottom of this image

rightMargin

intThe margin from the right side of this image

Response

Image

Constants

SCALE_FILL

Value 1
const

integer

since

2.5.0

SCALE_INSIDE

Value 2
const

integer

since

2.5.0

SCALE_OUTSIDE

Value 3
const

integer

since

2.5.0

CROP

Value 4
const

integer

since

2.5.0

CROP_RESIZE

Value 5
const

integer

since

2.5.0

SCALE_FIT

Value 6
const

integer

since

2.5.0

ORIENTATION_LANDSCAPE

Value 'landscape'
const

string

since

3.4.2

ORIENTATION_PORTRAIT

Value 'portrait'
const

string

since

3.4.2

ORIENTATION_SQUARE

Value 'square'
const

string

since

3.4.2

Properties

handle

The image resource handle.

since

2.5.0

Type(s)

resource

path

The source image path.

since

2.5.0

Type(s)

string

formats

Whether or not different image formats are supported.

static
since

2.5.0

Type(s)

array<string|int, mixed>

generateBestQuality

Flag if an image should use the best quality available. Disable for improved performance.

since

3.7.0

Type(s)

bool