class IconImageUploader

Stores an image used in place of a model's Font Awesome icon (a group's or a tag's, for example). The model needs the `icon_image_path` and `icon_image_scales` columns; see the HasIconImage concern.

Each upload is stored as a static WebP, its transparent border trimmed, and scaled to fit a square box at 1x, 2x and 3x without cropping, so that an image can be shown whole next to a label or cropped to a badge's shape by the browser. A model can use a subclass, with another box size, scales or disk, by overriding HasIconImage::iconImageUploader().

Properties

protected int $baseSize The box, in pixels, the 1x image is scaled to fit.
protected array<int, string> $scales The variants stored for each image: each scale's file name suffix, in ascending order. Scale 1 must have the empty suffix.
protected string $diskName
protected Cloud $disk

Methods

__construct( Factory $filesystemFactory, LoggerInterface $logger)

No description

void
upload( AbstractModel $model, ImageInterface $image)

Store the image's variants and point the model at them. The previous image's files are deleted once the model is saved and committed.

void
remove( AbstractModel $model)

Clear the model's image. Its files are deleted once the model is saved and committed.

void
revert( AbstractModel $model)

Undo upload() or remove() after saving the model threw. Nothing is undone if the row was written anyway (a `saved` listener can throw after that); otherwise an uploaded image's files are deleted and the model's previous image is restored.

string|null
url( AbstractModel $model)

No description

string|null
srcset( AbstractModel $model)

The srcset for the model's image, built from the stored scale count rather than by checking the disk. Null when there are no HiDPI variants.

bool
deleteAllVariants(string $basePath)

Delete an image's base file and every variant stored with it. Returns false if a file could not be deleted from a disk that doesn't throw.

void
deleteAllVariantsAfterCommit( AbstractModel $model, string $basePath)

Delete an image's files once the current transaction commits (at once outside a transaction). By then the change is stored, so a failure is logged rather than thrown: the files are orphaned, nothing is broken.

void
deleteAllVariantsOrLog(string $basePath)

Delete an image's files as clean-up, where a failure must not replace the error being handled or fail a change that is already stored.

void
removeFilesAfterSave( AbstractModel $model)

No description

bool
isStored( AbstractModel $model, string|null $path)

Whether the model's row in the database already holds the path.

void
trimTransparentBorder( ImageInterface $image)

Crop away a fully transparent border, so that the artwork, not the empty space around it, fills the glyph-sized box it is shown in. Only transparency is trimmed: a solid background is part of the design.

string
variantPath(string $basePath, string $suffix)

The path of a variant: 'abc.webp' with '@2x' is 'abc@2x.webp'.

Details

__construct( Factory $filesystemFactory, LoggerInterface $logger)

Parameters

Factory $filesystemFactory
LoggerInterface $logger

void upload( AbstractModel $model, ImageInterface $image)

Store the image's variants and point the model at them. The previous image's files are deleted once the model is saved and committed.

If the model then fails to save, call revert().

Parameters

AbstractModel $model
ImageInterface $image

Return Value

void

void remove( AbstractModel $model)

Clear the model's image. Its files are deleted once the model is saved and committed.

Parameters

AbstractModel $model

Return Value

void

void revert( AbstractModel $model)

Undo upload() or remove() after saving the model threw. Nothing is undone if the row was written anyway (a `saved` listener can throw after that); otherwise an uploaded image's files are deleted and the model's previous image is restored.

Parameters

AbstractModel $model

Return Value

void

string|null url( AbstractModel $model)

Parameters

AbstractModel $model

Return Value

string|null

string|null srcset( AbstractModel $model)

The srcset for the model's image, built from the stored scale count rather than by checking the disk. Null when there are no HiDPI variants.

Parameters

AbstractModel $model

Return Value

string|null

bool deleteAllVariants(string $basePath)

Delete an image's base file and every variant stored with it. Returns false if a file could not be deleted from a disk that doesn't throw.

Parameters

string $basePath

Return Value

bool

void deleteAllVariantsAfterCommit( AbstractModel $model, string $basePath)

Delete an image's files once the current transaction commits (at once outside a transaction). By then the change is stored, so a failure is logged rather than thrown: the files are orphaned, nothing is broken.

Parameters

AbstractModel $model
string $basePath

Return Value

void

protected void deleteAllVariantsOrLog(string $basePath)

Delete an image's files as clean-up, where a failure must not replace the error being handled or fail a change that is already stored.

Parameters

string $basePath

Return Value

void

protected void removeFilesAfterSave( AbstractModel $model)

Parameters

AbstractModel $model

Return Value

void

protected bool isStored( AbstractModel $model, string|null $path)

Whether the model's row in the database already holds the path.

Parameters

AbstractModel $model
string|null $path

Return Value

bool

protected void trimTransparentBorder( ImageInterface $image)

Crop away a fully transparent border, so that the artwork, not the empty space around it, fills the glyph-sized box it is shown in. Only transparency is trimmed: a solid background is part of the design.

The border is found on a small copy, which is quick whatever the source's size, and the crop errs on the side of keeping pixels.

Parameters

ImageInterface $image

Return Value

void

protected string variantPath(string $basePath, string $suffix)

The path of a variant: 'abc.webp' with '@2x' is 'abc@2x.webp'.

Parameters

string $basePath
string $suffix

Return Value

string