Cecil

Image

Image Asset class.

Provides methods to manipulate images, such as resizing, cropping, converting, and generating data URLs.

This class uses the Intervention Image library to handle image processing. It supports GD, Imagick and libvips drivers, depending on available extensions.

Table of Contents

Methods

buildDarkAssetPath()  : string
Builds the asset path for a dark color-scheme image variant.
buildDarkSourceAttributes()  : array<string|int, array<string, string>>
Builds dark color-scheme source attributes for an image.
buildHtmlSrcset()  : string
Alias of buildHtmlSrcsetW for backward compatibility.
buildHtmlSrcsetW()  : string
Build the `srcset` HTML attribute for responsive images, based on widths.
buildHtmlSrcsetX()  : string
Build the `srcset` HTML attribute for responsive images, based on pixel ratios.
buildIco()  : string
Builds an ICO file containing a single icon (PNG or BMP DIB data).
convert()  : string
Converts an image Asset to the target format.
dibToPng()  : string|null
Converts a 24 or 32 bits BMP icon (DIB data of an ICO file) to PNG.
extractIcoLargestIcon()  : string
Returns the binary data (PNG or BMP DIB) of the largest icon of an ICO file.
getBackgroundColor()  : string
Returns the background RGB color of an image asset.
getDataUrl()  : string
Returns the Data URL (encoded in Base64).
getDominantColor()  : string
Returns the dominant RGB color of an image asset.
getDriverName()  : string|null
Returns the name of the available image driver (e.g.: "Imagick"), or null if none.
getHtmlSizes()  : string
Returns the value from the `$sizes` array if the class exists, otherwise returns the default size.
getIcoSize()  : array{int, int}
Returns the size (width and height) of the largest icon of an ICO file.
getLqip()  : string
Returns a Low Quality Image Placeholder (LQIP) as data URL.
getSvgAttributes()  : SimpleXMLElement|false
Returns SVG attributes.
isAnimatedGif()  : bool
Checks if an asset is an animated GIF.
isIco()  : bool
Returns true if asset is an ICO.
isImage()  : bool
Asset is a valid image?
isSVG()  : bool
Returns true if asset is a SVG.
maskable()  : string
Makes an image Asset maskable, meaning it can be used as a PWA icon.
resize()  : string
Resizes an image Asset to the given width or/and height.
resizeIco()  : string
Resizes an ICO Asset to the given width or/and height.
driver()  : array{string, class-string}|null
Returns the available driver as [name, class], or null if none.
getIcoLargestEntry()  : array<string, int>
Returns the directory entry of the largest icon of an ICO file.
isVipsAvailable()  : bool
Checks if libvips can be loaded through FFI (php-vips v2+ does not rely on ext-vips).
manager()  : ImageManagerInterface
Create new manager instance with available driver.
url()  : string
Returns the URL of an Asset, built with the URL builder if provided.

Methods

buildDarkAssetPath()

Builds the asset path for a dark color-scheme image variant.

public static buildDarkAssetPath(string $assetPath, string $darkSuffix) : string
Parameters
$assetPath : string
$darkSuffix : string
Return values
string

buildDarkSourceAttributes()

Builds dark color-scheme source attributes for an image.

public static buildDarkSourceAttributes(Builder $builder, Asset $asset, string $darkSuffix, array<string|int, string> $formats[, array{responsive?: mixed, widths?: int[], densities?: (float|int)[], sizes?: ?string, width1x?: ?int, assetOptions?: array, url?: ?callable} $options = [] ]) : array<string|int, array<string, string>>
Parameters
$builder : Builder
$asset : Asset
$darkSuffix : string
$formats : array<string|int, string>
$options : array{responsive?: mixed, widths?: int[], densities?: (float|int)[], sizes?: ?string, width1x?: ?int, assetOptions?: array, url?: ?callable} = []
Return values
array<string|int, array<string, string>>

buildHtmlSrcset()

Alias of buildHtmlSrcsetW for backward compatibility.

public static buildHtmlSrcset(Asset $asset, array<string|int, mixed> $widths[, mixed $notEmpty = false ][, callable|null $url = null ]) : string
Parameters
$asset : Asset
$widths : array<string|int, mixed>
$notEmpty : mixed = false
$url : callable|null = null
Return values
string

buildHtmlSrcsetW()

Build the `srcset` HTML attribute for responsive images, based on widths.

public static buildHtmlSrcsetW(Asset $asset, array<string|int, mixed> $widths[, bool $notEmpty = false ][, callable|null $url = null ]) : string

e.g.: srcset="/img-480.jpg 480w, /img-800.jpg 800w".

Parameters
$asset : Asset
$widths : array<string|int, mixed>

An array of widths to include in the srcset

$notEmpty : bool = false

If true the source image is always added to the srcset

$url : callable|null = null

Optional URL builder, called with each Asset (e.g.: to handle base URL)

Tags
throws
RuntimeException
Return values
string

buildHtmlSrcsetX()

Build the `srcset` HTML attribute for responsive images, based on pixel ratios.

public static buildHtmlSrcsetX(Asset $asset, int $width1x, array<string|int, mixed> $ratios[, callable|null $url = null ]) : string

e.g.: srcset="/img-1x.jpg 1.0x, /img-2x.jpg 2.0x".

Parameters
$asset : Asset
$width1x : int

The width of the 1x image

$ratios : array<string|int, mixed>

An array of pixel ratios to include in the srcset

$url : callable|null = null

Optional URL builder, called with each Asset (e.g.: to handle base URL)

Tags
throws
RuntimeException
Return values
string

buildIco()

Builds an ICO file containing a single icon (PNG or BMP DIB data).

public static buildIco(string $icon, int $width, int $height[, int $bpp = 32 ]) : string
Parameters
$icon : string
$width : int
$height : int
$bpp : int = 32
Return values
string

convert()

Converts an image Asset to the target format.

public static convert(Asset $asset, string $format, int $quality) : string
Parameters
$asset : Asset
$format : string
$quality : int
Tags
throws
RuntimeException
Return values
string

dibToPng()

Converts a 24 or 32 bits BMP icon (DIB data of an ICO file) to PNG.

public static dibToPng(string $dib) : string|null

Returns null if the BMP icon format is not supported (other color depth or compression).

Parameters
$dib : string
Tags
throws
RuntimeException
Return values
string|null

extractIcoLargestIcon()

Returns the binary data (PNG or BMP DIB) of the largest icon of an ICO file.

public static extractIcoLargestIcon(string $data) : string

A PNG file (e.g.: renamed in ".ico") is returned as is.

Parameters
$data : string
Tags
throws
RuntimeException
Return values
string

getBackgroundColor()

Returns the background RGB color of an image asset.

public static getBackgroundColor(Asset $asset) : string
Parameters
$asset : Asset
Tags
throws
RuntimeException
Return values
string

getDataUrl()

Returns the Data URL (encoded in Base64).

public static getDataUrl(Asset $asset, int $quality) : string
Parameters
$asset : Asset
$quality : int
Tags
throws
RuntimeException
Return values
string

getDominantColor()

Returns the dominant RGB color of an image asset.

public static getDominantColor(Asset $asset) : string
Parameters
$asset : Asset
Tags
throws
RuntimeException
Return values
string

getDriverName()

Returns the name of the available image driver (e.g.: "Imagick"), or null if none.

public static getDriverName() : string|null
Return values
string|null

getHtmlSizes()

Returns the value from the `$sizes` array if the class exists, otherwise returns the default size.

public static getHtmlSizes(string $class[, array<string|int, mixed> $sizes = [] ]) : string
Parameters
$class : string
$sizes : array<string|int, mixed> = []
Return values
string

getIcoSize()

Returns the size (width and height) of the largest icon of an ICO file.

public static getIcoSize(string $data) : array{int, int}

Unlike getimagesize(), which doesn't necessarily return the size of the largest icon.

Parameters
$data : string
Tags
throws
RuntimeException
Return values
array{int, int}

getLqip()

Returns a Low Quality Image Placeholder (LQIP) as data URL.

public static getLqip(Asset $asset) : string
Parameters
$asset : Asset
Tags
throws
RuntimeException
Return values
string

getSvgAttributes()

Returns SVG attributes.

public static getSvgAttributes(Asset $asset) : SimpleXMLElement|false
Parameters
$asset : Asset
Return values
SimpleXMLElement|false

isAnimatedGif()

Checks if an asset is an animated GIF.

public static isAnimatedGif(Asset $asset) : bool
Parameters
$asset : Asset
Return values
bool

isIco()

Returns true if asset is an ICO.

public static isIco(Asset $asset) : bool
Parameters
$asset : Asset
Return values
bool

isImage()

Asset is a valid image?

public static isImage(Asset $asset) : bool
Parameters
$asset : Asset
Return values
bool

isSVG()

Returns true if asset is a SVG.

public static isSVG(Asset $asset) : bool
Parameters
$asset : Asset
Return values
bool

maskable()

Makes an image Asset maskable, meaning it can be used as a PWA icon.

public static maskable(Asset $asset, int $quality, int $padding) : string
Parameters
$asset : Asset
$quality : int
$padding : int
Tags
throws
RuntimeException
Return values
string

resize()

Resizes an image Asset to the given width or/and height.

public static resize(Asset $asset[, int|null $width = null ][, int|null $height = null ][, int $quality = 75 ][, bool $rmAnimation = false ]) : string

If both width and height are provided, the image is cropped to fit the dimensions. If only one dimension is provided, the image is scaled proportionally. The $rmAnimation parameter can be set to true to remove animations from animated images (e.g., GIFs).

Parameters
$asset : Asset
$width : int|null = null
$height : int|null = null
$quality : int = 75
$rmAnimation : bool = false
Tags
throws
RuntimeException
Return values
string

resizeIco()

Resizes an ICO Asset to the given width or/and height.

public static resizeIco(Asset $asset[, int|null $width = null ][, int|null $height = null ]) : string

The largest icon of the ICO file is resized and returned as a single PNG-compressed icon. PNG icons and 24/32 bits BMP icons are handled by any driver, other BMP icons require the Imagick extension.

Parameters
$asset : Asset
$width : int|null = null
$height : int|null = null
Tags
throws
RuntimeException
Return values
string

driver()

Returns the available driver as [name, class], or null if none.

private static driver() : array{string, class-string}|null
Return values
array{string, class-string}|null

getIcoLargestEntry()

Returns the directory entry of the largest icon of an ICO file.

private static getIcoLargestEntry(string $data) : array<string, int>
Parameters
$data : string
Tags
throws
RuntimeException
Return values
array<string, int>

isVipsAvailable()

Checks if libvips can be loaded through FFI (php-vips v2+ does not rely on ext-vips).

private static isVipsAvailable() : bool
Return values
bool

manager()

Create new manager instance with available driver.

private static manager() : ImageManagerInterface
Return values
ImageManagerInterface

url()

Returns the URL of an Asset, built with the URL builder if provided.

private static url(Asset $asset[, callable|null $url = null ]) : string
Parameters
$asset : Asset
$url : callable|null = null
Return values
string
On this page

Search results