CoolCMS API

AssetVariantPlan
in package

FinalYes

Pure functions of image variants stored in the DB. No DB or DI, so they can be covered by a unit test ({@see \Tests\Unit\System\AssetVariantPlanTest}).

  • buildPlans(): DB rows (usage x assignment x variant) to an upload plan in the same shape the neon config used to give (array<folder, {maxWidth, maxHeight, resizeFlags, useWatermark}>), plus the keys variant, alias, original (the renderer ignores them).
  • validateAssignments(): assignment rules of one usage.
  • validateVariant(): variant rules; height 0 means no height limit.

Table of Contents

Constants

KEY_PATTERN  : string = '~^[a-z0-9-]{1,32}$~'
Technical variant key and alias: lowercase letters, digits, hyphen.
MAX_DIMENSION  : int = 8000
Upper bound of a variant dimension in px (width starts at 1, height at 0 = no height limit).
ORIGINAL_FOLDER  : string = 'original'
Original folder: not a variant, only the `keep_original` flag of a usage.
REQUIRED_ALIASES  : array<string|int, mixed> = ['big', 'thumb']
Aliases every usage must have (admin preview and lists / detail and og:image).
REQUIRED_ALIASES_BY_USAGE  : array<string|int, mixed> = ['system-identity-favicon' => ['icon32', 'icon1...
Required aliases per usage, deviating from {@see REQUIRED_ALIASES}. Theme templates (`<head>`, operator card) request these folders by name, so they cannot be disabled or renamed.
RESERVED_NAMES  : array<string|int, mixed> = ['original', 'big', 'thumb']
Variant names that would be confused with aliases and the original folder.

Methods

buildPlans()  : array<string, array<string, array{maxWidth: int, maxHeight: int, resizeFlags: list, useWatermark: bool, variant: string|null, alias: string|null, original?: bool}>>
normalizeAlias()  : string|null
An empty alias gives null; an invalid format gives null too (callers tell them apart by the raw value).
requiredAliasesFor()  : array<int, string>
Aliases the assignment of the given usage must have. An unknown usage requires `big` + `thumb`.
validateAssignments()  : array<int, array{code: string, variantId: int|null, alias: string|null}>
Assignment rules of one usage. Returns a list of errors (empty = valid).
validateVariant()  : array<int, array{code: string, field: string, other: string|null}>
Variant rules: name format and reservation, dimensions 1..MAX, mode, uniqueness of the name and of the technical parameters.
hasErrorForAlias()  : bool
toBool()  : bool
toInt()  : int
Number from a DB row (DBAL returns strings); anything non-numeric gives 0.
toStr()  : string

Constants

KEY_PATTERN

Technical variant key and alias: lowercase letters, digits, hyphen.

public string KEY_PATTERN = '~^[a-z0-9-]{1,32}$~'

MAX_DIMENSION

Upper bound of a variant dimension in px (width starts at 1, height at 0 = no height limit).

public int MAX_DIMENSION = 8000

ORIGINAL_FOLDER

Original folder: not a variant, only the `keep_original` flag of a usage.

public string ORIGINAL_FOLDER = 'original'

REQUIRED_ALIASES

Aliases every usage must have (admin preview and lists / detail and og:image).

public array<string|int, mixed> REQUIRED_ALIASES = ['big', 'thumb']

REQUIRED_ALIASES_BY_USAGE

Required aliases per usage, deviating from {@see REQUIRED_ALIASES}. Theme templates (`<head>`, operator card) request these folders by name, so they cannot be disabled or renamed.

public array<string|int, mixed> REQUIRED_ALIASES_BY_USAGE = ['system-identity-favicon' => ['icon32', 'icon180', 'icon512'], 'system-identity-logo' => ['thumb'], 'system-operator-photo' => ['avatar', 'thumb'], 'system-images' => ['thumb']]

RESERVED_NAMES

Variant names that would be confused with aliases and the original folder.

public array<string|int, mixed> RESERVED_NAMES = ['original', 'big', 'thumb']

Methods

buildPlans()

public static buildPlans(iterable<string|int, array<string, mixed>> $rows) : array<string, array<string, array{maxWidth: int, maxHeight: int, resizeFlags: list, useWatermark: bool, variant: string|null, alias: string|null, original?: bool}>>
Parameters
$rows : iterable<string|int, array<string, mixed>>

rows with keys usage_key, keep_original, variant_id, variant_name, max_width, max_height, resize_mode, watermark, activated, alias, assignment_position (LEFT JOIN: a usage without an assignment has variant_id null)

Return values
array<string, array<string, array{maxWidth: int, maxHeight: int, resizeFlags: list, useWatermark: bool, variant: string|null, alias: string|null, original?: bool}>> —

only usages with at least one active assigned variant

normalizeAlias()

An empty alias gives null; an invalid format gives null too (callers tell them apart by the raw value).

public static normalizeAlias(mixed $alias) : string|null
Parameters
$alias : mixed
Return values
string|null

requiredAliasesFor()

Aliases the assignment of the given usage must have. An unknown usage requires `big` + `thumb`.

public static requiredAliasesFor(string $usageKey) : array<int, string>
Parameters
$usageKey : string
Return values
array<int, string>

validateAssignments()

Assignment rules of one usage. Returns a list of errors (empty = valid).

public static validateAssignments(bool $keepOriginal, array<int, array{variantId: int, alias: string|null}> $assignments, array<int, array{name: string, activated: bool}> $variants[, string $usageKey = '' ]) : array<int, array{code: string, variantId: int|null, alias: string|null}>
Parameters
$keepOriginal : bool
$assignments : array<int, array{variantId: int, alias: string|null}>

checked variants

$variants : array<int, array{name: string, activated: bool}>

all variants by id

$usageKey : string = ''

usage key, determines the required aliases (requiredAliasesFor()); empty = big + thumb

Return values
array<int, array{code: string, variantId: int|null, alias: string|null}> —

codes: aliasFormat, aliasReserved, aliasDuplicate, folderDuplicate, variantUnknown, variantInactive, missingAlias

validateVariant()

Variant rules: name format and reservation, dimensions 1..MAX, mode, uniqueness of the name and of the technical parameters.

public static validateVariant(string $name, int $maxWidth, int $maxHeight, string $resizeMode, bool $watermark, array<int, array{id: int, name: string, maxWidth: int, maxHeight: int, resizeMode: string, watermark: bool}> $others) : array<int, array{code: string, field: string, other: string|null}>
Parameters
$name : string
$maxWidth : int
$maxHeight : int
$resizeMode : string
$watermark : bool
$others : array<int, array{id: int, name: string, maxWidth: int, maxHeight: int, resizeMode: string, watermark: bool}>

other variants (without the one being saved)

Return values
array<int, array{code: string, field: string, other: string|null}> —

codes: nameFormat, nameReserved, nameTaken, dimension, resizeMode, coverNeedsHeight, paramsTaken

hasErrorForAlias()

private static hasErrorForAlias(array<int, array{code: string, variantId: int|null, alias: string|null}> $errors, string $alias) : bool
Parameters
$errors : array<int, array{code: string, variantId: int|null, alias: string|null}>
$alias : string
Return values
bool

toBool()

private static toBool(mixed $value) : bool
Parameters
$value : mixed
Return values
bool

toInt()

Number from a DB row (DBAL returns strings); anything non-numeric gives 0.

private static toInt(mixed $value) : int
Parameters
$value : mixed
Return values
int

toStr()

private static toStr(mixed $value) : string
Parameters
$value : mixed
Return values
string
On this page

Search results