1. trait
  2. SilverStripe
  3. \
  4. Assets
  5. \
  6. ImageManipulation

ImageManipulation

trait ImageManipulation

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

Config options

force_resample bool Force all images to resample in all cases Off by default, as this can be resource intensive to apply to multiple images simultaneously.
strip_thumbnail_width int
strip_thumbnail_height int
cms_thumbnail_width int The width of an image thumbnail in the CMS.
cms_thumbnail_height int The height of an image thumbnail in the CMS.
asset_preview_width int The width of an image preview in the Asset section
asset_preview_height int 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

DBFile
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

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

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

AssetContainer
Resampled()

Forces the image to be resampled, if possible

updateURL(string $url)

Update the url to point to a resampled version if forcing

AssetContainer
ResizedImage(int $width, int $height)

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

AssetContainer
Fit(int $width, int $height)

Scale image proportionally to fit within the specified bounds

AssetContainer
FitMax(int $width, int $height)

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

AssetContainer
ScaleWidth(int $width)

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

AssetContainer
ScaleMaxWidth(int $width)

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

AssetContainer
ScaleHeight(int $height)

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

AssetContainer
ScaleMaxHeight(int $height)

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

AssetContainer
CropWidth(int $width)

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

AssetContainer
CropHeight(int $height)

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

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.

AssetContainer
Fill(int $width, int $height)

Resize and crop image to fill specified dimensions.

AssetContainer
Quality(int $quality)

Set the quality of the resampled image

DBFile|DBHTMLText
CMSThumbnail()

Default CMS thumbnail

AssetContainer|DBHTMLText
StripThumbnail()

Generates a thumbnail for use in the gridfield view

AssetContainer|DBHTMLText
PreviewThumbnail()

Get preview for this file

AssetContainer
Thumbnail(int $width, int $height)

Default thumbnail generation for Images

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

Thumbnail generation for all file types.

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

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

boolean
isSize(int $width, int $height)

Determine if this image is of the specified size

boolean
isWidth(int $width)

Determine if this image is of the specified width

boolean
isHeight(int $height)

Determine if this image is of the specified width

DBFile
manipulateImage(string $variant, callable $callback)

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

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.

string
variantName($format, $arg = null)

Name a variant based on a format with arbitrary parameters

array|null
variantParts($variantName)

Reverses {@link variantName()}.

Details

at line 67
$this setAllowGeneration(bool $allow)

Set whether image resizes are allowed

Parameters

bool $allow

Return Value

$this

at line 78
bool getAllowGeneration()

Check if resizes are allowed

Return Value

bool

at line 88
DBFile existingOnly()

Return clone of self which promises to only return existing thumbnails

Return Value

DBFile

at line 104
abstract string getString()

Return Value

string Data from the file in this container

at line 109
abstract resource getStream()

Return Value

resource Data stream to the asset in this container

at line 115
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

at line 120
abstract string getAbsoluteURL()

Return Value

string The absolute URL to the asset in this container

at line 127
abstract array|null getMetaData()

Get metadata for this file

Return Value

array|null File information

at line 134
abstract string getMimeType()

Get mime type

Return Value

string Mime type for this file

at line 141
abstract int getAbsoluteSize()

Return file size in bytes.

Return Value

int

at line 148
abstract bool exists()

Determine if this container has a valid value

Return Value

bool Flag as to whether the file exists

at line 155
abstract string getFilename()

Get value of filename

Return Value

string

at line 162
abstract string getHash()

Get value of hash

Return Value

string

at line 169
abstract string getVariant()

Get value of variant

Return Value

string

at line 176
abstract bool getIsImage()

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

Return Value

bool

at line 241
AssetContainer Pad(int $width, int $height, string $backgroundColor = 'FFFFFF', int $transparencyPercent)

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

at line 262
AssetContainer Resampled()

Forces the image to be resampled, if possible

Return Value

AssetContainer

at line 285
updateURL(string $url)

Update the url to point to a resampled version if forcing

Parameters

string $url

at line 314
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

at line 334
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

at line 375
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

at line 419
AssetContainer ScaleWidth(int $width)

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

Parameters

int $width The width to set

Return Value

AssetContainer

at line 439
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

at line 457
AssetContainer ScaleHeight(int $height)

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

Parameters

int $height The height to set

Return Value

AssetContainer

at line 477
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

at line 498
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

at line 520
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

at line 544
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

at line 584
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

at line 604
AssetContainer Quality(int $quality)

Set the quality of the resampled image

Parameters

int $quality Quality level from 0 - 100

Return Value

AssetContainer

Exceptions

InvalidArgumentException

at line 618
DBFile|DBHTMLText CMSThumbnail()

Default CMS thumbnail

Return Value

DBFile|DBHTMLText Either a resized thumbnail, or html for a thumbnail icon

at line 630
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

at line 642
AssetContainer|DBHTMLText PreviewThumbnail()

Get preview for this file

Return Value

AssetContainer|DBHTMLText Either a resized thumbnail, or html for a thumbnail icon

at line 655
AssetContainer Thumbnail(int $width, int $height)

Default thumbnail generation for Images

Parameters

int $width
int $height

Return Value

AssetContainer

at line 669
AssetContainer|DBHTMLText ThumbnailIcon(int $width, int $height)

Thumbnail 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

at line 679
DBHTMLText IconTag()

Get HTML for img containing the icon for this file

Return Value

DBHTMLText

at line 698
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

at line 714
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

at line 726
Image_Backend getImageBackend()

Get Image_Backend instance for this image

Return Value

Image_Backend

at line 751
$this setImageBackend(Image_Backend $backend)

Parameters

Image_Backend $backend

Return Value

$this

at line 762
int getWidth()

Get the width of this image.

Return Value

int

at line 776
int getHeight()

Get the height of this image.

Return Value

int

at line 790
int getOrientation()

Get the orientation of this image.

Return Value

int ORIENTATION_SQUARE | ORIENTATION_PORTRAIT | ORIENTATION_LANDSCAPE

at line 810
boolean 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

boolean

at line 821
boolean isWidth(int $width)

Determine if this image is of the specified width

Parameters

int $width Width to check

Return Value

boolean

at line 833
boolean isHeight(int $height)

Determine if this image is of the specified width

Parameters

int $height Height to check

Return Value

boolean

at line 847
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

at line 917
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

at line 994
string variantName($format, $arg = null)

Name a variant based on a format with arbitrary parameters

Parameters

$format
$arg

Return Value

string

at line 1013
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