trait ImageManipulation (View source)

Provides image manipulation functionality.

Provides limited thumbnail generation functionality for non-image files. Should only be applied to implementors of AssetContainer

Allows raw images to be resampled via Resampled()

Image scaling manipluations, including:

  • Fit()
  • FitMax()
  • ScaleWidth()
  • ScaleMaxWidth()
  • ScaleHeight()
  • ScaleMaxHeight()
  • ResizedImage()

Image cropping manipulations, including:

  • CropHeight()
  • CropWidth()
  • Fill()
  • FillMax()

Thumbnail generation methods including:

  • Icon()
  • CMSThumbnail()

Properties

static private bool $force_resample

Force all images to resample in all cases Off by default, as this can be resource intensive to apply to multiple images simultaneously.

static private int $strip_thumbnail_width
static private int $strip_thumbnail_height
static private int $cms_thumbnail_width

The width of an image thumbnail in the CMS.

static private int $cms_thumbnail_height

The height of an image thumbnail in the CMS.

static private int $asset_preview_width

The width of an image preview in the Asset section

static private int $asset_preview_height

The height of an image preview in the Asset section

Methods

$this
setAllowGeneration(bool $allow)

Set whether image resizes are allowed

bool
getAllowGeneration()

Check if resizes are allowed

existingOnly()

Return clone of self which promises to only return existing thumbnails

string
getString()

No description

resource
getStream()

No description

string
getURL(bool $grant = true)

No description

string
getAbsoluteURL()

No description

array|null
getMetaData()

Get metadata for this file

string
getMimeType()

Get mime type

int
getAbsoluteSize()

Return file size in bytes.

bool
exists()

Determine if this container has a valid value

string
getFilename()

Get value of filename

string
getHash()

Get value of hash

string
getVariant()

Get value of variant

bool
getIsImage()

Determine if a valid non-empty image exists behind this asset

Pad(int $width, int $height, string $backgroundColor = 'FFFFFF', int $transparencyPercent = 0)

Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.

Resampled()

Forces the image to be resampled, if possible

updateURL(string $url)

Update the url to point to a resampled version if forcing

ResizedImage(int $width, int $height)

Generate a resized copy of this image with the given width & height.

Fit(int $width, int $height)

Scale image proportionally to fit within the specified bounds

FitMax(int $width, int $height)

Proportionally scale down this image if it is wider or taller than the specified dimensions.

ScaleWidth(int $width)

Scale image proportionally by width. Use in templates with $ScaleWidth.

ScaleMaxWidth(int $width)

Proportionally scale down this image if it is wider than the specified width.

ScaleHeight(int $height)

Scale image proportionally by height. Use in templates with $ScaleHeight.

ScaleMaxHeight(int $height)

Proportionally scale down this image if it is taller than the specified height.

CropWidth(int $width)

Crop image on X axis if it exceeds specified width. Retain height.

CropHeight(int $height)

Crop image on Y axis if it exceeds specified height. Retain width.

FillMax(int $width, int $height)

Crop this image to the aspect ratio defined by the specified width and height, then scale down the image to those dimensions if it exceeds them.

Fill(int $width, int $height)

Resize and crop image to fill specified dimensions.

Quality(int $quality)

Set the quality of the resampled image

CMSThumbnail()

Default CMS thumbnail

StripThumbnail()

Generates a thumbnail for use in the gridfield view

PreviewThumbnail()

Get preview for this file

Thumbnail(int $width, int $height)

Default thumbnail generation for Images

ThumbnailIcon(int $width, int $height)

Thubnail generation for all file types.

IconTag()

Get HTML for img containing the icon for this file

string
ThumbnailURL(int $width, int $height)

Get URL to thumbnail of the given size.

string
getIcon()

Return the relative URL of an icon for the file type, based on the {@link appCategory()} value.

getImageBackend()

Get Image_Backend instance for this image

$this
setImageBackend(Image_Backend $backend)

No description

int
getWidth()

Get the width of this image.

int
getHeight()

Get the height of this image.

int
getOrientation()

Get the orientation of this image.

bool
isSize(int $width, int $height)

Determine if this image is of the specified size

bool
isWidth(int $width)

Determine if this image is of the specified width

bool
isHeight(int $height)

Determine if this image is of the specified width

manipulateImage(string $variant, callable $callback)

Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples

manipulate(string $variant, callable $callback)

Generate a new DBFile instance using the given callback if it hasn't been created yet, or return the existing one if it has.

string
variantName(string $format, $arg = null)

Name a variant based on a format with arbitrary parameters

array|null
variantParts($variantName)

Reverses {@link variantName()}.

Details

$this setAllowGeneration(bool $allow)

Set whether image resizes are allowed

Parameters

bool $allow

Return Value

$this

bool getAllowGeneration()

Check if resizes are allowed

Return Value

bool

DBFile existingOnly()

Return clone of self which promises to only return existing thumbnails

Return Value

DBFile

abstract string getString()

Return Value

string

Data from the file in this container

abstract resource getStream()

Return Value

resource

Data stream to the asset in this container

abstract string getURL(bool $grant = true)

Parameters

bool $grant

Ensures that the url for any protected assets is granted for the current user.

Return Value

string

public url to the asset in this container

abstract string getAbsoluteURL()

Return Value

string

The absolute URL to the asset in this container

abstract array|null getMetaData()

Get metadata for this file

Return Value

array|null

File information

abstract string getMimeType()

Get mime type

Return Value

string

Mime type for this file

abstract int getAbsoluteSize()

Return file size in bytes.

Return Value

int

abstract bool exists()

Determine if this container has a valid value

Return Value

bool

Flag as to whether the file exists

abstract string getFilename()

Get value of filename

Return Value

string

abstract string getHash()

Get value of hash

Return Value

string

abstract string getVariant()

Get value of variant

Return Value

string

abstract bool getIsImage()

Determine if a valid non-empty image exists behind this asset

Return Value

bool

AssetContainer Pad(int $width, int $height, string $backgroundColor = 'FFFFFF', int $transparencyPercent = 0)

Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.

Parameters

int $width

The width to size to

int $height

The height to size to

string $backgroundColor
int $transparencyPercent

Level of transparency

Return Value

AssetContainer

AssetContainer Resampled()

Forces the image to be resampled, if possible

Return Value

AssetContainer

updateURL(string $url)

Update the url to point to a resampled version if forcing

Parameters

string $url

AssetContainer ResizedImage(int $width, int $height)

Generate a resized copy of this image with the given width & height.

This can be used in templates with $ResizedImage but should be avoided, as it's the only image manipulation function which can skew an image.

Parameters

int $width

Width to resize to

int $height

Height to resize to

Return Value

AssetContainer

AssetContainer Fit(int $width, int $height)

Scale image proportionally to fit within the specified bounds

Parameters

int $width

The width to size within

int $height

The height to size within

Return Value

AssetContainer

AssetContainer FitMax(int $width, int $height)

Proportionally scale down this image if it is wider or taller than the specified dimensions.

Similar to Fit but without up-sampling. Use in templates with $FitMax.

Parameters

int $width

The maximum width of the output image

int $height

The maximum height of the output image

Return Value

AssetContainer

AssetContainer ScaleWidth(int $width)

Scale image proportionally by width. Use in templates with $ScaleWidth.

Parameters

int $width

The width to set

Return Value

AssetContainer

AssetContainer ScaleMaxWidth(int $width)

Proportionally scale down this image if it is wider than the specified width.

Similar to ScaleWidth but without up-sampling. Use in templates with $ScaleMaxWidth.

Parameters

int $width

The maximum width of the output image

Return Value

AssetContainer

AssetContainer ScaleHeight(int $height)

Scale image proportionally by height. Use in templates with $ScaleHeight.

Parameters

int $height

The height to set

Return Value

AssetContainer

AssetContainer ScaleMaxHeight(int $height)

Proportionally scale down this image if it is taller than the specified height.

Similar to ScaleHeight but without up-sampling. Use in templates with $ScaleMaxHeight.

Parameters

int $height

The maximum height of the output image

Return Value

AssetContainer

AssetContainer CropWidth(int $width)

Crop image on X axis if it exceeds specified width. Retain height.

Use in templates with $CropWidth. Example: $Image.ScaleHeight(100).$CropWidth(100)

Parameters

int $width

The maximum width of the output image

Return Value

AssetContainer

AssetContainer CropHeight(int $height)

Crop image on Y axis if it exceeds specified height. Retain width.

Use in templates with $CropHeight. Example: $Image.ScaleWidth(100).CropHeight(100)

Parameters

int $height

The maximum height of the output image

Return Value

AssetContainer

AssetContainer FillMax(int $width, int $height)

Crop this image to the aspect ratio defined by the specified width and height, then scale down the image to those dimensions if it exceeds them.

Similar to Fill but without up-sampling. Use in templates with $FillMax.

Parameters

int $width

The relative (used to determine aspect ratio) and maximum width of the output image

int $height

The relative (used to determine aspect ratio) and maximum height of the output image

Return Value

AssetContainer

AssetContainer Fill(int $width, int $height)

Resize and crop image to fill specified dimensions.

Use in templates with $Fill

Parameters

int $width

Width to crop to

int $height

Height to crop to

Return Value

AssetContainer

AssetContainer Quality(int $quality)

Set the quality of the resampled image

Parameters

int $quality

Quality level from 0 - 100

Return Value

AssetContainer

Exceptions

InvalidArgumentException

DBFile|DBHTMLText CMSThumbnail()

Default CMS thumbnail

Return Value

DBFile|DBHTMLText

Either a resized thumbnail, or html for a thumbnail icon

AssetContainer|DBHTMLText StripThumbnail()

Generates a thumbnail for use in the gridfield view

Return Value

AssetContainer|DBHTMLText

Either a resized thumbnail, or html for a thumbnail icon

AssetContainer|DBHTMLText PreviewThumbnail()

Get preview for this file

Return Value

AssetContainer|DBHTMLText

Either a resized thumbnail, or html for a thumbnail icon

AssetContainer Thumbnail(int $width, int $height)

Default thumbnail generation for Images

Parameters

int $width
int $height

Return Value

AssetContainer

AssetContainer|DBHTMLText ThumbnailIcon(int $width, int $height)

Thubnail generation for all file types.

Resizes images, but returns an icon <img /> tag if this is not a resizable image

Parameters

int $width
int $height

Return Value

AssetContainer|DBHTMLText

DBHTMLText IconTag()

Get HTML for img containing the icon for this file

Return Value

DBHTMLText

string ThumbnailURL(int $width, int $height)

Get URL to thumbnail of the given size.

May fallback to default icon

Parameters

int $width
int $height

Return Value

string

string getIcon()

Return the relative URL of an icon for the file type, based on the {@link appCategory()} value.

Images are searched for in "framework/images/app_icons/".

Return Value

string

URL to icon

Image_Backend getImageBackend()

Get Image_Backend instance for this image

Return Value

Image_Backend

$this setImageBackend(Image_Backend $backend)

Parameters

Image_Backend $backend

Return Value

$this

int getWidth()

Get the width of this image.

Return Value

int

int getHeight()

Get the height of this image.

Return Value

int

int getOrientation()

Get the orientation of this image.

Return Value

int

ORIENTATION_SQUARE | ORIENTATION_PORTRAIT | ORIENTATION_LANDSCAPE

bool isSize(int $width, int $height)

Determine if this image is of the specified size

Parameters

int $width

Width to check

int $height

Height to check

Return Value

bool

bool isWidth(int $width)

Determine if this image is of the specified width

Parameters

int $width

Width to check

Return Value

bool

bool isHeight(int $height)

Determine if this image is of the specified width

Parameters

int $height

Height to check

Return Value

bool

DBFile manipulateImage(string $variant, callable $callback)

Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples

Parameters

string $variant
callable $callback

Callback which takes an Image_Backend object, and returns an Image_Backend result. If this callback returns true then the current image will be duplicated without modification.

Return Value

DBFile

The manipulated file

DBFile manipulate(string $variant, callable $callback)

Generate a new DBFile instance using the given callback if it hasn't been created yet, or return the existing one if it has.

Parameters

string $variant

name of the variant to create

callable $callback

Callback which should return a new tuple as an array. This callback will be passed the backend, filename, hash, and variant This will not be called if the file does not need to be created.

Return Value

DBFile

The manipulated file

string variantName(string $format, $arg = null)

Name a variant based on a format with arbitrary parameters

Parameters

string $format

The format name.

$arg

Return Value

string

array|null variantParts($variantName)

Reverses {@link variantName()}.

The "format" part of a variant name is a method name on the owner of this trait. For legacy reasons, there's no delimiter between this part, and the encoded arguments. This means we have to use a whitelist of "known formats", based on methods available on the {@link Image} class as the "main" user of this trait. This class is commonly decorated with additional manipulation methods through {@link DataExtension}.

Parameters

$variantName

Return Value

array|null

An array of arguments passed to {@link variantName}. The first item is the "format".

Exceptions

InvalidArgumentException