Documentation

ImageMedium extends Medium
in package
implements ImageMediaInterface, ImageManipulateInterface uses ImageMediaTrait, ImageLoadingTrait, ImageDecodingTrait, ImageFetchPriorityTrait

Class ImageMedium

Table of Contents

Interfaces

ImageMediaInterface
Class implements image media interface.
ImageManipulateInterface
Class implements image manipulation interface.

Properties

$basename  : string
$filename  : string
$filepath  : string
$magic_actions  : array<string|int, mixed>
$magic_resize_actions  : array<string|int, mixed>
$metadata  : array<string|int, mixed>
$mime  : string
$modified  : int
$size  : int
$timestamp  : int|string
$_thumbnail  : MediaObjectInterface|null
$alternatives  : array<string|int, MediaObjectInterface>
$aspect_ratio  : bool
$attributes  : array<string|int, mixed>
$auto_sizes  : bool
$blueprints  : Blueprint|callable|null
$debug_watermarked  : bool
$default_quality  : int
$format  : string
$gettersVariable  : string
$image  : ImageFile|null
$items  : array<string|int, mixed>
$medium_querystring  : array<string|int, mixed>
$mode  : string
$parsedown  : Parsedown|null
$quality  : int
$retina_scale  : int
$sizes  : string
$storage  : FileInterface|null
$styleAttributes  : array<string|int, mixed>
$thumbnailType  : string|null
$thumbnailTypes  : array<string|int, mixed>
$watermark  : bool
$saved_image_path  : mixed|string

Methods

__call()  : $this|mixed
Forward the call to the image processing method.
__clone()  : mixed
Also clone image.
__construct()  : mixed
Construct.
__destruct()  : mixed
Also unset the image on destruct.
__toString()  : string
Return string representation of the object (html).
addAlternative()  : mixed
Add alternative Medium to this Medium.
addFrame()  : $this
Add a frame to image
addMetaFile()  : $this
Add meta file for the medium.
aspectRatio()  : $this
attribute()  : $this
Add custom attribute to medium.
autoSizes()  : $this
blueprints()  : Blueprint
Return blueprints.
cache()  : $this
Simply processes with no extra methods. Useful for triggering events.
classes()  : $this
Add a class to the element from Markdown or Twig Example: ![Example](myimg.png?classes=float-left) or ![Example](myimg.png?classes=myclass1,myclass2)
clearAlternatives()  : mixed
Clear out the alternatives.
copy()  : static
Create a copy of this media object
cropZoom()  : $this
Handle this commonly used variant
decoding()  : $this
Allows to set the decoding attribute from Markdown or Twig
derivatives()  : $this
Generate alternative image widths, using either an array of integers, or a min width, a max width, and a step parameter to fill out the necessary widths. Existing image alternatives won't be overwritten.
display()  : MediaObjectInterface|null
Switch display mode.
exists()  : bool
Check if this medium exists or not
extra()  : array<string|int, mixed>
Get extra items which haven't been defined in blueprints.
fetchpriority()  : $this
Allows to set the fetchpriority attribute from Markdown or Twig
file()  : FileInterface|null
Set or get the data storage.
filter()  : $this
Filter image by using user defined filter parameters.
format()  : $this
Sets image output format.
get()  : mixed
Get value by using dot notation for nested arrays/objects.
getAlternatives()  : array<string|int, mixed>
getDefaults()  : array<string|int, mixed>
Get nested structure containing default values defined in the blueprints.
getImagePrettyName()  : string
getJoined()  : array<string|int, mixed>
Get value from the configuration and join it with given data.
getMeta()  : array<string|int, mixed>
Returns an array containing the file metadata
height()  : $this
Allows to set the height attribute from Markdown or Twig Examples: ![Example](myimg.png?width=200&height=400) ![Example](myimg.png?resize=100,200&width=100&height=200) ![Example](myimg.png?width=auto&height=auto) ![Example](myimg.png?width&height) {{ page.media['myimg.png'].width().height().html }} {{ page.media['myimg.png'].resize(100,200).width(100).height(200).html }}
higherQualityAlternative()  : ImageMediaInterface|$this
Return the image higher quality version
html()  : string
Return HTML markup from the medium.
id()  : $this
Add an id to the element from Markdown or Twig Example: ![Example](myimg.png?id=primary-img)
join()  : $this
Join nested values together by using blueprints.
joinDefaults()  : $this
Set default values by using blueprints.
jsonSerialize()  : array<string|int, mixed>
lightbox()  : MediaLinkInterface
Turn the current Medium into a Link with lightbox enabled
link()  : MediaLinkInterface
Turn the current Medium into a Link
loading()  : $this
Allows to set the loading attribute from Markdown or Twig
merge()  : $this
Merge two configurations together.
meta()  : Data
Return just metadata from the Medium object
metadata()  : array<string|int, mixed>
Returns an array containing just the metadata
modified()  : int|null
Get file modification time for the medium.
parsedownElement()  : array<string|int, mixed>
Get an element (is array) that can be rendered by the Parsedown engine
path()  : string
Return PATH to image.
quality()  : int|$this
Sets or gets the quality of the image
querystring()  : string
Get/set querystring for the file's url
raw()  : string
Return unmodified data as raw string.
relativePath()  : string
Return the relative path to file
reset()  : $this
Reset image.
retinaScale()  : $this
save()  : void
Save data if storage has been defined.
set()  : $this
Set value by using dot notation for nested arrays/objects.
setDefaults()  : $this
Set default values to the configuration if variables were not set.
setImagePrettyName()  : mixed
Allows the ability to override the image's pretty name stored in cache
setKeepEmptyValues()  : $this
setMissingValuesAsNull()  : $this
setTimestamp()  : $this
Set querystring to file modification timestamp (or value provided as a parameter).
size()  : int
Get size of the medium.
sizes()  : string
Set or get sizes parameter for srcset media action
sourceParsedownElement()  : array<string|int, mixed>
Parsedown element for source display mode
srcset()  : string
Return srcset string for this Medium and its alternatives.
style()  : $this
Allows to add an inline style attribute from Markdown or Twig Example: ![Example](myimg.png?style=float:left)
thumbnail()  : $this
Switch thumbnail.
thumbnailExists()  : bool
Helper method to determine if this media item has a thumbnail or not
url()  : string
Return URL to image.
urlHash()  : string
Get/set hash for the file's url
urlQuerystring()  : string
Get the URL with full querystring
validate()  : $this
Validate by blueprints.
value()  : mixed
Get value by using dot notation for nested arrays/objects.
watermark()  : $this
width()  : $this
Allows to set the width attribute from Markdown or Twig Examples: ![Example](myimg.png?width=200&height=400) ![Example](myimg.png?resize=100,200&width=100&height=200) ![Example](myimg.png?width=auto&height=auto) ![Example](myimg.png?width&height) {{ page.media['myimg.png'].width().height().html }} {{ page.media['myimg.png'].resize(100,200).width(100).height(200).html }}
createLink()  : MediaLinkInterface
createThumbnail()  : Medium|null
getGrav()  : Grav
getItems()  : array<string|int, mixed>
getThumbnail()  : ThumbnailImageMedium|null
Get the thumbnail Medium object
image()  : $this
Gets medium image, resets image manipulation operations.
saveImage()  : string
Save the image with cache.
textParsedownElement()  : array<string|int, mixed>
Parsedown element for text display mode

Properties

$basename

public string $basename

$filename

public string $filename

$filepath

public string $filepath

$magic_actions

public static array<string|int, mixed> $magic_actions = ['resize', 'forceResize', 'cropResize', 'crop', 'zoomCrop', 'negate', 'brightness', 'contrast', 'grayscale', 'emboss', 'smooth', 'sharp', 'edge', 'colorize', 'sepia', 'enableProgressive', 'rotate', 'flip', 'fixOrientation', 'gaussianBlur', 'format', 'create', 'fill', 'merge']

$magic_resize_actions

public static array<string|int, mixed> $magic_resize_actions = ['resize' => [0, 1], 'forceResize' => [0, 1], 'cropResize' => [0, 1], 'crop' => [0, 1, 2, 3], 'zoomCrop' => [0, 1]]

$metadata

public array<string|int, mixed> $metadata

$timestamp

public int|string $timestamp

$gettersVariable

protected string $gettersVariable = 'items'

$items

protected array<string|int, mixed> $items

$medium_querystring

protected array<string|int, mixed> $medium_querystring = []

$storage

protected FileInterface|null $storage

$styleAttributes

protected array<string|int, mixed> $styleAttributes = []

$thumbnailTypes

protected array<string|int, mixed> $thumbnailTypes = ['page', 'default']

$saved_image_path

private mixed|string $saved_image_path

Methods

__call()

Forward the call to the image processing method.

public __call(string $method, mixed $args) : $this|mixed
Parameters
$method : string
$args : mixed
Attributes
#[ReturnTypeWillChange]
Return values
$this|mixed

__clone()

Also clone image.

public __clone() : mixed
Attributes
#[ReturnTypeWillChange]

__construct()

Construct.

public __construct([array<string|int, mixed> $items = [] ][, Blueprint|null $blueprint = null ]) : mixed
Parameters
$items : array<string|int, mixed> = []
$blueprint : Blueprint|null = null

__destruct()

Also unset the image on destruct.

public __destruct() : mixed
Attributes
#[ReturnTypeWillChange]

__toString()

Return string representation of the object (html).

public __toString() : string
Attributes
#[ReturnTypeWillChange]
Return values
string

addFrame()

Add a frame to image

public addFrame([int $border = 10 ][, string $color = '0x000000' ]) : $this
Parameters
$border : int = 10
$color : string = '0x000000'
Return values
$this

addMetaFile()

Add meta file for the medium.

public addMetaFile(string $filepath) : $this
Parameters
$filepath : string
Return values
$this

aspectRatio()

public aspectRatio([string $enabled = 'true' ]) : $this
Parameters
$enabled : string = 'true'
Return values
$this

attribute()

Add custom attribute to medium.

public attribute([string $attribute = null ][, string $value = '' ]) : $this
Parameters
$attribute : string = null
$value : string = ''
Return values
$this

autoSizes()

public autoSizes([string $enabled = 'true' ]) : $this
Parameters
$enabled : string = 'true'
Return values
$this

cache()

Simply processes with no extra methods. Useful for triggering events.

public cache() : $this
Return values
$this

classes()

Add a class to the element from Markdown or Twig Example: ![Example](myimg.png?classes=float-left) or ![Example](myimg.png?classes=myclass1,myclass2)

public classes() : $this
Return values
$this

clearAlternatives()

Clear out the alternatives.

public clearAlternatives() : mixed

copy()

Create a copy of this media object

public copy() : static
Return values
static

cropZoom()

Handle this commonly used variant

public cropZoom() : $this
Return values
$this

decoding()

Allows to set the decoding attribute from Markdown or Twig

public decoding([string|null $value = null ]) : $this
Parameters
$value : string|null = null
Return values
$this

derivatives()

Generate alternative image widths, using either an array of integers, or a min width, a max width, and a step parameter to fill out the necessary widths. Existing image alternatives won't be overwritten.

public derivatives(int|array<string|int, int> $min_width[, int $max_width = 2500 ][, int $step = 200 ]) : $this
Parameters
$min_width : int|array<string|int, int>
$max_width : int = 2500
$step : int = 200
Return values
$this

exists()

Check if this medium exists or not

public exists() : bool
Return values
bool

extra()

Get extra items which haven't been defined in blueprints.

public extra() : array<string|int, mixed>
Return values
array<string|int, mixed>

fetchpriority()

Allows to set the fetchpriority attribute from Markdown or Twig

public fetchpriority([string|null $value = null ]) : $this
Parameters
$value : string|null = null
Return values
$this

file()

Set or get the data storage.

public file([FileInterface|null $storage = null ]) : FileInterface|null
Parameters
$storage : FileInterface|null = null

Optionally enter a new storage.

Return values
FileInterface|null

filter()

Filter image by using user defined filter parameters.

public filter([string $filter = 'image.filters.default' ]) : $this
Parameters
$filter : string = 'image.filters.default'

Filter to be used.

Return values
$this

format()

Sets image output format.

public format(string $format) : $this
Parameters
$format : string
Return values
$this

get()

Get value by using dot notation for nested arrays/objects.

public abstract get(string $name[, mixed $default = null ][, string|null $separator = null ]) : mixed
Parameters
$name : string

Dot separated path to the requested value.

$default : mixed = null

Default value (or null).

$separator : string|null = null

Separator, defaults to '.'

Tags
example

$value = $this->get('this.is.my.nested.variable');

Return values
mixed

Value.

getAlternatives()

public getAlternatives([bool $withDerived = true ]) : array<string|int, mixed>
Parameters
$withDerived : bool = true
Return values
array<string|int, mixed>

getDefaults()

Get nested structure containing default values defined in the blueprints.

public getDefaults() : array<string|int, mixed>

Fields without default value are ignored in the list.

Return values
array<string|int, mixed>

getImagePrettyName()

public getImagePrettyName() : string
Return values
string

getJoined()

Get value from the configuration and join it with given data.

public getJoined(string $name, array<string|int, mixed>|object $value[, string $separator = '.' ]) : array<string|int, mixed>
Parameters
$name : string

Dot separated path to the requested value.

$value : array<string|int, mixed>|object

Value to be joined.

$separator : string = '.'

Separator, defaults to '.'

Tags
throws
RuntimeException
Return values
array<string|int, mixed>

getMeta()

Returns an array containing the file metadata

public getMeta() : array<string|int, mixed>
Return values
array<string|int, mixed>

height()

Allows to set the height attribute from Markdown or Twig Examples: ![Example](myimg.png?width=200&height=400) ![Example](myimg.png?resize=100,200&width=100&height=200) ![Example](myimg.png?width=auto&height=auto) ![Example](myimg.png?width&height) {{ page.media['myimg.png'].width().height().html }} {{ page.media['myimg.png'].resize(100,200).width(100).height(200).html }}

public height([string|int $value = 'auto' ]) : $this
Parameters
$value : string|int = 'auto'

A value or 'auto' or empty to use the height of the image

Return values
$this

html()

Return HTML markup from the medium.

public html([string|null $title = null ][, string|null $alt = null ][, string|null $class = null ][, string|null $id = null ][, bool $reset = true ]) : string
Parameters
$title : string|null = null
$alt : string|null = null
$class : string|null = null
$id : string|null = null
$reset : bool = true
Return values
string

id()

Add an id to the element from Markdown or Twig Example: ![Example](myimg.png?id=primary-img)

public id(string $id) : $this
Parameters
$id : string
Return values
$this

join()

Join nested values together by using blueprints.

public join(string $name, mixed $value[, string $separator = '.' ]) : $this
Parameters
$name : string

Dot separated path to the requested value.

$value : mixed

Value to be joined.

$separator : string = '.'

Separator, defaults to '.'

Tags
throws
RuntimeException
Return values
$this

joinDefaults()

Set default values by using blueprints.

public joinDefaults(string $name, mixed $value[, string $separator = '.' ]) : $this
Parameters
$name : string

Dot separated path to the requested value.

$value : mixed

Value to be joined.

$separator : string = '.'

Separator, defaults to '.'

Return values
$this

jsonSerialize()

public jsonSerialize() : array<string|int, mixed>
Attributes
#[ReturnTypeWillChange]
Return values
array<string|int, mixed>

lightbox()

Turn the current Medium into a Link with lightbox enabled

public lightbox([int $width = null ][, int $height = null ][, bool $reset = true ]) : MediaLinkInterface
Parameters
$width : int = null
$height : int = null
$reset : bool = true
Return values
MediaLinkInterface

Turn the current Medium into a Link

public link([bool $reset = true ][, array<string|int, mixed> $attributes = [] ]) : MediaLinkInterface
Parameters
$reset : bool = true
$attributes : array<string|int, mixed> = []
Return values
MediaLinkInterface

loading()

Allows to set the loading attribute from Markdown or Twig

public loading([string|null $value = null ]) : $this
Parameters
$value : string|null = null
Return values
$this

merge()

Merge two configurations together.

public merge(array<string|int, mixed> $data) : $this
Parameters
$data : array<string|int, mixed>
Return values
$this

metadata()

Returns an array containing just the metadata

public metadata() : array<string|int, mixed>
Return values
array<string|int, mixed>

modified()

Get file modification time for the medium.

public modified() : int|null
Return values
int|null

parsedownElement()

Get an element (is array) that can be rendered by the Parsedown engine

public parsedownElement([string|null $title = null ][, string|null $alt = null ][, string|null $class = null ][, string|null $id = null ][, bool $reset = true ]) : array<string|int, mixed>
Parameters
$title : string|null = null
$alt : string|null = null
$class : string|null = null
$id : string|null = null
$reset : bool = true
Return values
array<string|int, mixed>

path()

Return PATH to image.

public path([bool $reset = true ]) : string
Parameters
$reset : bool = true
Return values
string

path to image

quality()

Sets or gets the quality of the image

public quality([int|null $quality = null ]) : int|$this
Parameters
$quality : int|null = null

0-100 quality

Return values
int|$this

querystring()

Get/set querystring for the file's url

public querystring([string|null $querystring = null ][, bool $withQuestionmark = true ]) : string
Parameters
$querystring : string|null = null
$withQuestionmark : bool = true
Return values
string

raw()

Return unmodified data as raw string.

public raw() : string

NOTE: This function only returns data which has been saved to the storage.

Return values
string

relativePath()

Return the relative path to file

public relativePath([bool $reset = true ]) : string
Parameters
$reset : bool = true
Return values
string

reset()

Reset image.

public reset() : $this
Return values
$this

retinaScale()

public retinaScale([int $scale = 1 ]) : $this
Parameters
$scale : int = 1
Return values
$this

save()

Save data if storage has been defined.

public save() : void
Tags
throws
RuntimeException

set()

Set value by using dot notation for nested arrays/objects.

public abstract set(string $name, mixed $value[, string|null $separator = null ]) : $this
Parameters
$name : string

Dot separated path to the requested value.

$value : mixed

New value.

$separator : string|null = null

Separator, defaults to '.'

Tags
example

$data->set('this.is.my.nested.variable', $value);

Return values
$this

setDefaults()

Set default values to the configuration if variables were not set.

public setDefaults(array<string|int, mixed> $data) : $this
Parameters
$data : array<string|int, mixed>
Return values
$this

setImagePrettyName()

Allows the ability to override the image's pretty name stored in cache

public setImagePrettyName(string $name) : mixed
Parameters
$name : string

setKeepEmptyValues()

public setKeepEmptyValues(bool $value) : $this
Parameters
$value : bool
Return values
$this

setMissingValuesAsNull()

public setMissingValuesAsNull(bool $value) : $this
Parameters
$value : bool
Return values
$this

setTimestamp()

Set querystring to file modification timestamp (or value provided as a parameter).

public setTimestamp([string|int|null $timestamp = null ]) : $this
Parameters
$timestamp : string|int|null = null
Return values
$this

size()

Get size of the medium.

public size() : int
Return values
int

sizes()

Set or get sizes parameter for srcset media action

public sizes([string|null $sizes = null ]) : string
Parameters
$sizes : string|null = null
Return values
string

sourceParsedownElement()

Parsedown element for source display mode

public sourceParsedownElement(array<string|int, mixed> $attributes[, bool $reset = true ]) : array<string|int, mixed>
Parameters
$attributes : array<string|int, mixed>
$reset : bool = true
Return values
array<string|int, mixed>

srcset()

Return srcset string for this Medium and its alternatives.

public srcset([bool $reset = true ]) : string
Parameters
$reset : bool = true
Return values
string

style()

Allows to add an inline style attribute from Markdown or Twig Example: ![Example](myimg.png?style=float:left)

public style(string $style) : $this
Parameters
$style : string
Return values
$this

thumbnail()

Switch thumbnail.

public thumbnail([string $type = 'auto' ]) : $this
Parameters
$type : string = 'auto'
Return values
$this

thumbnailExists()

Helper method to determine if this media item has a thumbnail or not

public thumbnailExists([string $type = 'page' ]) : bool
Parameters
$type : string = 'page'

;

Return values
bool

url()

Return URL to image.

public url([bool $reset = true ]) : string
Parameters
$reset : bool = true
Return values
string

urlHash()

Get/set hash for the file's url

public urlHash([string|null $hash = null ][, bool $withHash = true ]) : string
Parameters
$hash : string|null = null
$withHash : bool = true
Return values
string

urlQuerystring()

Get the URL with full querystring

public urlQuerystring(string $url) : string
Parameters
$url : string
Return values
string

validate()

Validate by blueprints.

public validate() : $this
Tags
throws
Exception
Return values
$this

value()

Get value by using dot notation for nested arrays/objects.

public value(string $name[, mixed $default = null ][, string $separator = '.' ]) : mixed
Parameters
$name : string

Dot separated path to the requested value.

$default : mixed = null

Default value (or null).

$separator : string = '.'

Separator, defaults to '.'

Tags
example

$value = $data->value('this.is.my.nested.variable');

Return values
mixed

Value.

watermark()

public watermark([string|null $image = null ][, string|null $position = null ][, int|float|null $scale = null ]) : $this
Parameters
$image : string|null = null
$position : string|null = null
$scale : int|float|null = null
Return values
$this

width()

Allows to set the width attribute from Markdown or Twig Examples: ![Example](myimg.png?width=200&height=400) ![Example](myimg.png?resize=100,200&width=100&height=200) ![Example](myimg.png?width=auto&height=auto) ![Example](myimg.png?width&height) {{ page.media['myimg.png'].width().height().html }} {{ page.media['myimg.png'].resize(100,200).width(100).height(200).html }}

public width([string|int $value = 'auto' ]) : $this
Parameters
$value : string|int = 'auto'

A value or 'auto' or empty to use the width of the image

Return values
$this

createThumbnail()

protected createThumbnail(string $thumb) : Medium|null
Parameters
$thumb : string
Return values
Medium|null

getItems()

protected getItems() : array<string|int, mixed>
Return values
array<string|int, mixed>

image()

Gets medium image, resets image manipulation operations.

protected image() : $this
Return values
$this

saveImage()

Save the image with cache.

protected saveImage() : string
Return values
string

textParsedownElement()

Parsedown element for text display mode

protected textParsedownElement(array<string|int, mixed> $attributes[, bool $reset = true ]) : array<string|int, mixed>
Parameters
$attributes : array<string|int, mixed>
$reset : bool = true
Return values
array<string|int, mixed>

        
On this page

Search results