trait ImageManipulation mixin AssetContainer (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()

Other manipulations that do not create variants:

  • LazyLoad()

Traits

This trait can be applied to a ViewableData class to add the logic to render attributes in an SS template.

Properties

protected array $attributes

List of attributes to render on the frontend

from  AttributesHTML
protected Image_Backend $imageBackend
protected bool $allowGeneration

If image resizes are allowed

Methods

public
setAttribute(string $name, mixed $value)

Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.

public
mixed|null
getAttribute(string $name)

Retrieve the value of an HTML attribute

protected
array
getDefaultAttributes()

No description

public
array
getAttributes()

Allows customization through an 'updateAttributes' hook on the base class.

public
string
getAttributesHTML(array $attributes = null)

Custom attributes to process. Falls back to getAttributes().

public
$this
setAllowGeneration(bool $allow)

Set whether image resizes are allowed

public
bool
getAllowGeneration()

Check if resizes are allowed

public
existingOnly()

Return clone of self which promises to only return existing thumbnails

public
string
getString()

No description

public
resource
getStream()

No description

public
string
getURL(bool $grant = true)

No description

public
string
getAbsoluteURL()

No description

public
array|null
getMetaData()

Get metadata for this file

public
string
getMimeType()

Get mime type

public
int
getAbsoluteSize()

Return file size in bytes.

public
bool
exists()

Determine if this container has a valid value

public
string
getFilename()

Get value of filename

public
string
getHash()

Get value of hash

public
string
getVariant()

Get value of variant

public
bool
getIsImage()

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

public
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.

public
Resampled()

Forces the image to be resampled, if possible

public
updateURL(string $url)

Update the url to point to a resampled version if forcing

public
ResizedImage(int $width, int $height)

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

public
Fit(int $width, int $height)

Scale image proportionally to fit within the specified bounds

public
FitMax(int $width, int $height)

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

public
ScaleWidth(int $width)

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

public
ScaleMaxWidth(int $width)

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

public
ScaleHeight(int $height)

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

public
ScaleMaxHeight(int $height)

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

public
CropWidth(int $width)

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

public
CropHeight(int $height)

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

public
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.

public
Fill(int $width, int $height)

Resize and crop image to fill specified dimensions.

public
Quality(int $quality)

Set the quality of the resampled image

public
CMSThumbnail()

Default CMS thumbnail

public
StripThumbnail()

Generates a thumbnail for use in the gridfield view

public
PreviewThumbnail()

Get preview for this file

public
Thumbnail(int $width, int $height)

Default thumbnail generation for Images

public
ThumbnailIcon(int $width, int $height)

Thubnail generation for all file types.

public
IconTag()

Get HTML for img containing the icon for this file

public
string
ThumbnailURL(int $width, int $height)

Get URL to thumbnail of the given size.

public
AssetContainer|null
Convert(string $toExtension)

Convert the file to another format if there's a registered converter that can handle it.

public
string
getIcon()

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

public
getImageBackend()

Get Image_Backend instance for this image

public
$this
setImageBackend(Image_Backend $backend)

No description

public
int
getWidth()

Get the width of this image.

public
int
getHeight()

Get the height of this image.

public
int
getOrientation()

Get the orientation of this image.

public
bool
isSize(int $width, int $height)

Determine if this image is of the specified size

public
bool
isWidth(int $width)

Determine if this image is of the specified width

public
bool
isHeight(int $height)

Determine if this image is of the specified width

public
DBFile|null
manipulateExtension(string $newExtension, callable $callback)

Wrapper for manipulate() that creates a variant file with a different extension than the original file.

public
DBFile|null
manipulateImage(string $variant, callable $callback)

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

public
DBFile|null
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.

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

Name a variant based on a format with arbitrary parameters

public
array|null
variantParts($variantName)

Reverses variantName().

protected
int
castDimension(mixed $value, string $dimension)

Validate a width or size is valid and casts it to integer

public
bool
IsLazyLoaded()

Determine whether the image should be lazy loaded

public
LazyLoad(mixed $lazyLoad)

Set the lazy loading state for this Image

Details

AssetContainer setAttribute(string $name, mixed $value)

Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.

Parameters

string $name
mixed $value

Return Value

AssetContainer

mixed|null getAttribute(string $name)

Retrieve the value of an HTML attribute

Parameters

string $name

Return Value

mixed|null

protected array getDefaultAttributes()

No description

Return Value

array

array getAttributes()

Allows customization through an 'updateAttributes' hook on the base class.

Existing attributes are passed in as the first argument and can be manipulated, but any attributes added through a subclass implementation won't be included.

Return Value

array

string getAttributesHTML(array $attributes = null)

Custom attributes to process. Falls back to getAttributes().

If at least one argument is passed as a string, all arguments act as excludes, by name.

Parameters

array $attributes

Return Value

string

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

No description

Return Value

string

Data from the file in this container

abstract resource getStream()

No description

Return Value

resource

Data stream to the asset in this container

abstract string getURL(bool $grant = true)

No description

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

No description

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

AssetContainer|null Convert(string $toExtension)

Convert the file to another format if there's a registered converter that can handle it.

Parameters

string $toExtension

The file extension you want to convert to - e.g. "webp".

Return Value

AssetContainer|null

Exceptions

FileConverterException

string getIcon()

Return the relative URL of an icon for the file type, based on the 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)

No description

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|null manipulateExtension(string $newExtension, callable $callback)

Wrapper for manipulate() that creates a variant file with a different extension than the original file.

Parameters

string $newExtension
callable $callback

Return Value

DBFile|null

The manipulated file

DBFile|null 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|null

The manipulated file

DBFile|null 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|null

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 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 Image class as the "main" user of this trait. The one exception to this is the variant for swapping file extensions, which is explicitly allowed. This class is commonly decorated with additional manipulation methods through DataExtension.

Parameters

$variantName

Return Value

array|null

An array of arguments passed to variantName. The first item is the "format".

Exceptions

InvalidArgumentException

protected int castDimension(mixed $value, string $dimension)

Validate a width or size is valid and casts it to integer

Parameters

mixed $value

value of dimension

string $dimension

Name of dimension

Return Value

int

Validated value

bool IsLazyLoaded()

Determine whether the image should be lazy loaded

Return Value

bool

AssetContainer LazyLoad(mixed $lazyLoad)

Set the lazy loading state for this Image

Parameters

mixed $lazyLoad

Return Value

AssetContainer