CoolCMS API

Asset extends BaseEntity
in package
implements IdentifiableInterface uses IdentifiableTrait, TranslationCollectionTrait

AbstractYes
Tags
template
Attributes
#[MappedSuperclass]
#[TableAlias]
$alias: 'asset'

Table of Contents

Interfaces

IdentifiableInterface
Entity with a simple integer primary key. Most entities have one (often via {@see \App\Core\Traits\Shared\Models\Entities\IdentifiableTrait}); texts and links with a composite key do not, which is why `getId()` is not on {@see \App\Core\Base\BaseEntity}. Code that needs the id of a generic entity asks for this interface (parameter type, template bound, `instanceof`).

Properties

$fileExtension  : string|null
$fileName  : string
$id  : int|null
$insertTime  : DateTime
$meta  : string|null
$path  : string
$thumbnailExtension  : string|null
$thumbnailsAttempts  : int
$thumbnailsGenerated  : bool
$translations  : Collection<int, TTranslation>
$usageKey  : string|null
$variants  : string|null
$variantsAttempts  : int

Methods

__construct()  : mixed
addTranslation()  : $this
callInitMethods()  : void
Calls `init{TraitName}()` for every used trait that defines such a method.
getAllTraits()  : array<string, string>
Returns all traits the class uses, including those used by parent classes and nested traits.
getFileExtension()  : string|null
getFileName()  : string
getFirstVariant()  : AssetVariant|null
Returns the first available variant from `meta` as a VO ({@see AssetVariant}) without knowing its name. For a general check that a file exists on the server (`getFirstVariant()?->exists()`) where it does not matter which variants the asset has (not every asset has `big`/`original`, some have none). Null means `meta` without variants (old asset or file outside the server).
getFullFileName()  : string
getFullPath()  : string
Return a full file path (with filename)
getId()  : int|null
getInsertTime()  : DateTime
getMeta()  : string|null
getMimeType()  : string
getPath()  : string
getPosterPath()  : string|null
Returns the path to the poster image of a video (prefers the 'big' variant).
getPosterVariant()  : AssetVariant|null
Returns the AssetVariant of the video poster (with URL and absolute path for `exists()`); null when there is no poster.
getSerializedVariants()  : string|null
getThumbnailExtension()  : string|null
Extension of the generated variants (poster/thumb/big) on disk.
getThumbnailPath()  : string
Returns the preview path: the `thumb` folder, otherwise the smallest downscaled variant, otherwise the original, and the full path ({@see getFullPath()}) without variants.
getThumbnailsAttempts()  : int
getThumbnailsGenerated()  : bool
getThumbnailVariant()  : AssetVariant|null
Returns the AssetVariant of the actually displayed preview (smallest available variant, otherwise the original); it carries the public URL and the absolute path, so `exists()` checks the file on disk. Independent of `meta`: the URL is built from the config variants / the original, so it works for assets without `meta` (dimensions are added from `meta` when present).
getTranslation()  : TTranslation|null
getTranslations()  : Collection<int, TTranslation>
getType()  : AssetType
Derived from $fileExtension — stays consistent if extension changes.
getUnserializedMeta()  : array<string, mixed>
getUnserializedVariants()  : array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>
Returns variants as plain associative arrays.
getUsageKey()  : string|null
getVariant()  : AssetVariant|null
Returns the real info about a variant as a VO ({@see AssetVariant}) from `meta`. The name is case-insensitive (lowercase). Resolution mirrors {@see getFullPath()}: the requested variant, otherwise `original`. Null means no real info for the variant (old asset or file outside the server: `meta` is empty; the backfill cron fills it).
getVariantFallbackOrder()  : array<int, string>
Returns variant folders in the order in which a missing file is substituted (no disk check): requested folder, then the nearest larger downscaled variant by width (downscaling loses nothing), then smaller descending, then the original. A placeholder image is added by the caller.
getVariantFiles()  : array<int, array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}>
Returns the variant files of a record without touching the disk: `folder` = `name` in lowercase, `original` = the `original` folder or the key `original: true`, `variant`/`alias` from the new record shape (the old one has none: null).
getVariants()  : string|null
getVariantsAttempts()  : int
getVariantsSortedByWidth()  : array<int, array<string, mixed>>
Returns variants sorted ascending by width (smallest first), original last.
hasThumbnails()  : bool
hasVariant()  : bool
hasVariants()  : bool
incrementThumbnailsAttempts()  : $this
isImage()  : bool
isPersisted()  : bool
isThumbnailsGenerated()  : bool
isVideo()  : bool
readyForUpload()  : bool
removeTranslation()  : $this
setFileExtension()  : $this
setFileName()  : $this
setId()  : $this
setInsertTime()  : $this
setMeta()  : $this
setPath()  : $this
setSerializedVariants()  : $this
setThumbnailExtension()  : $this
setThumbnailsAttempts()  : $this
setThumbnailsGenerated()  : $this
setTranslations()  : $this
setUnserializedMeta()  : $this
setUnserializedVariants()  : $this
Saves variants as plain associative arrays (new format).
setUsageKey()  : $this
setVariants()  : $this
setVariantsAttempts()  : $this
translationCollectionInit()  : void
buildVariant()  : AssetVariant|null
Builds an {@see AssetVariant} from a meta entry (URL + absolute path + dimensions); null for an invalid entry.
describeVariantFile()  : array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}|null
getMetaVariants()  : array<string, mixed>
getSortedVariantEntries()  : array<int, array{variant: array, file: array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}, width: int}>
Returns variants with a width for sorting: downscaled variants ascending (real width, otherwise `maxWidth`, otherwise at the end of the downscaled ones), the original last; a tie goes to the smaller `maxWidth`, then record order.
getTraitsRecursive()  : array<string, string>
Walks the trait list recursively and collects nested traits too.
intOf()  : int
normalizeVariants()  : array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>
Converts stored data (JSON / old serialize) to the variant shape; an item without a name is dropped (callers skipped it anyway), numbers and flags are cast, other keys stay.
resolveThumbnailFolder()  : string|null
Returns the preview folder per {@see getThumbnailPath()}; null means no variant to use.
textOf()  : string

Properties

$fileExtension

protected string|null $fileExtension = null
Attributes
#[Column]
$name: 'file_extension'
$type: 'string'
$length: 15
$nullable: true

$fileName

protected string $fileName = ''
Attributes
#[Column]
$name: 'file_name'
$type: 'string'
$length: 255

$id

protected int|null $id = null
Attributes
#[Column]
$name: 'image_id'
$type: 'integer'
$options: ['unsigned' => true]
#[GeneratedValue]
#[Id]

$insertTime

protected DateTime $insertTime = new DateTime()
Attributes
#[Column]
$name: 'insert_time'
$type: 'datetime'
#[ExternalReadonly]

$meta

protected string|null $meta = null
Attributes
#[Column]
$name: 'meta'
$type: 'text'
$nullable: true

$path

protected string $path = ''
Attributes
#[Column]
$name: 'path'
$type: 'string'
$length: 255

$thumbnailExtension

protected string|null $thumbnailExtension = null
Attributes
#[Column]
$name: 'thumbnail_extension'
$type: 'string'
$length: 15
$nullable: true

$thumbnailsAttempts

protected int $thumbnailsAttempts = 0
Attributes
#[Column]
$name: 'thumbnails_attempts'
$type: 'smallint'
$options: ['unsigned' => true, 'default' => 0]

$thumbnailsGenerated

protected bool $thumbnailsGenerated = false
Attributes
#[Column]
$name: 'thumbnails_generated'
$type: 'boolean'
$options: ['default' => false]

$translations

protected Collection<int, TTranslation> $translations = new ArrayCollection()

$usageKey

protected string|null $usageKey = null
Attributes
#[Column]
$name: 'usage_key'
$type: 'string'
$length: 64
$nullable: true
#[ExternalReadonly]

$variants

protected string|null $variants = null
Attributes
#[Column]
$name: 'variants'
$type: 'text'
$nullable: true

$variantsAttempts

protected int $variantsAttempts = 0
Attributes
#[Column]
$name: 'variants_attempts'
$type: 'smallint'
$options: ['unsigned' => true, 'default' => 0]
#[ExternalReadonly]

Methods

__construct()

public __construct([int|null $id = null ][, string $path = '' ][, string $fileName = '' ][, string|null $fileExtension = null ][, string|null $thumbnailExtension = null ][, DateTime $insertTime = new DateTime() ][, string|null $variants = null ][, string|null $meta = null ][, bool $thumbnailsGenerated = false ][, int $thumbnailsAttempts = 0 ][, string|null $usageKey = null ][, int $variantsAttempts = 0 ][, Collection $translations = new ArrayCollection() ]) : mixed
Parameters
$id : int|null = null
$path : string = ''
$fileName : string = ''
$fileExtension : string|null = null
$thumbnailExtension : string|null = null
$insertTime : DateTime = new DateTime()
$variants : string|null = null
$meta : string|null = null
$thumbnailsGenerated : bool = false
$thumbnailsAttempts : int = 0
$usageKey : string|null = null
$variantsAttempts : int = 0
$translations : Collection = new ArrayCollection()

addTranslation()

public addTranslation(TTranslation $translation) : $this
Parameters
$translation : TTranslation
Return values
$this

callInitMethods()

Calls `init{TraitName}()` for every used trait that defines such a method.

public callInitMethods() : void

getAllTraits()

Returns all traits the class uses, including those used by parent classes and nested traits.

public getAllTraits() : array<string, string>
Return values
array<string, string>

getFileExtension()

public getFileExtension() : string|null
Return values
string|null

getFileName()

public getFileName() : string
Return values
string

getFirstVariant()

Returns the first available variant from `meta` as a VO ({@see AssetVariant}) without knowing its name. For a general check that a file exists on the server (`getFirstVariant()?->exists()`) where it does not matter which variants the asset has (not every asset has `big`/`original`, some have none). Null means `meta` without variants (old asset or file outside the server).

public getFirstVariant() : AssetVariant|null
Return values
AssetVariant|null

getFullFileName()

public getFullFileName() : string
Return values
string

getFullPath()

Return a full file path (with filename)

public getFullPath([string $variant = null ]) : string
Parameters
$variant : string = null
Return values
string

getInsertTime()

public getInsertTime() : DateTime
Return values
DateTime

getMeta()

public getMeta() : string|null
Return values
string|null

getMimeType()

public getMimeType() : string
Return values
string

getPath()

public getPath() : string
Return values
string

getPosterPath()

Returns the path to the poster image of a video (prefers the 'big' variant).

public getPosterPath() : string|null

Returns null for images or a video without variants.

Return values
string|null

getPosterVariant()

Returns the AssetVariant of the video poster (with URL and absolute path for `exists()`); null when there is no poster.

public getPosterVariant() : AssetVariant|null
Return values
AssetVariant|null

getSerializedVariants()

public getSerializedVariants() : string|null
Return values
string|null

getThumbnailExtension()

Extension of the generated variants (poster/thumb/big) on disk.

public getThumbnailExtension() : string|null

Image: same as fileExtension (jpg/png/...). Video: 'jpg' after ffmpeg succeeds, null until the catch-up cron generates the variants. The renderer may rely on this value being filled for an asset with thumbnailsGenerated=true.

Return values
string|null

getThumbnailPath()

Returns the preview path: the `thumb` folder, otherwise the smallest downscaled variant, otherwise the original, and the full path ({@see getFullPath()}) without variants.

public getThumbnailPath() : string

Video: the thumb poster (only when posters are generated), otherwise the video file; never a path to a poster that is not on disk.

Return values
string

getThumbnailsAttempts()

public getThumbnailsAttempts() : int
Return values
int

getThumbnailsGenerated()

public getThumbnailsGenerated() : bool
Return values
bool

getThumbnailVariant()

Returns the AssetVariant of the actually displayed preview (smallest available variant, otherwise the original); it carries the public URL and the absolute path, so `exists()` checks the file on disk. Independent of `meta`: the URL is built from the config variants / the original, so it works for assets without `meta` (dimensions are added from `meta` when present).

public getThumbnailVariant() : AssetVariant|null
Return values
AssetVariant|null

getTranslation()

public getTranslation(int $langId) : TTranslation|null
Parameters
$langId : int
Return values
TTranslation|null

getTranslations()

public getTranslations() : Collection<int, TTranslation>
Return values
Collection<int, TTranslation>

getType()

Derived from $fileExtension — stays consistent if extension changes.

public getType() : AssetType
Return values
AssetType

getUnserializedMeta()

public getUnserializedMeta() : array<string, mixed>
Return values
array<string, mixed>

getUnserializedVariants()

Returns variants as plain associative arrays.

public getUnserializedVariants() : array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>

Automatically migrates legacy ImageVariantEntity serialized objects on read.

Return values
array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>

getUsageKey()

public getUsageKey() : string|null
Return values
string|null

getVariant()

Returns the real info about a variant as a VO ({@see AssetVariant}) from `meta`. The name is case-insensitive (lowercase). Resolution mirrors {@see getFullPath()}: the requested variant, otherwise `original`. Null means no real info for the variant (old asset or file outside the server: `meta` is empty; the backfill cron fills it).

public getVariant([string|null $variant = null ]) : AssetVariant|null
Parameters
$variant : string|null = null
Return values
AssetVariant|null

getVariantFallbackOrder()

Returns variant folders in the order in which a missing file is substituted (no disk check): requested folder, then the nearest larger downscaled variant by width (downscaling loses nothing), then smaller descending, then the original. A placeholder image is added by the caller.

public getVariantFallbackOrder([string|null $wanted = null ]) : array<int, string>

Without $wanted (or when the record does not know it and the width cannot be derived from a WxH / wN name) downscaled variants ascend and then comes the original, as list pages behave today.

Parameters
$wanted : string|null = null
Return values
array<int, string>

getVariantFiles()

Returns the variant files of a record without touching the disk: `folder` = `name` in lowercase, `original` = the `original` folder or the key `original: true`, `variant`/`alias` from the new record shape (the old one has none: null).

public getVariantFiles() : array<int, array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}>

width/height only from the real dimensions in meta.variants[folder]; without meta they are null and maxWidth is only an upper bound, so it must not become a w descriptor. Order as in the record.

Return values
array<int, array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}>

getVariants()

public getVariants() : string|null
Return values
string|null

getVariantsAttempts()

public getVariantsAttempts() : int
Return values
int

getVariantsSortedByWidth()

Returns variants sorted ascending by width (smallest first), original last.

public getVariantsSortedByWidth() : array<int, array<string, mixed>>

The width is the real one from meta, otherwise maxWidth. The original (maxWidth 0) would win the sort as "smallest", so it always comes after the downscaled variants. Useful for picking a thumbnail or building a gallery. Item shape is unchanged.

Return values
array<int, array<string, mixed>>

hasThumbnails()

public hasThumbnails() : bool
Return values
bool

hasVariant()

public hasVariant(string $variantName) : bool
Parameters
$variantName : string
Return values
bool

hasVariants()

public hasVariants() : bool
Return values
bool

incrementThumbnailsAttempts()

public incrementThumbnailsAttempts() : $this
Return values
$this

isImage()

public isImage() : bool
Return values
bool

isThumbnailsGenerated()

public isThumbnailsGenerated() : bool
Return values
bool

isVideo()

public isVideo() : bool
Return values
bool

readyForUpload()

public readyForUpload() : bool
Return values
bool

removeTranslation()

public removeTranslation(TTranslation $translation) : $this
Parameters
$translation : TTranslation
Return values
$this

setFileExtension()

public setFileExtension(string|null $fileExtension) : $this
Parameters
$fileExtension : string|null
Return values
$this

setFileName()

public setFileName(string $fileName) : $this
Parameters
$fileName : string
Return values
$this

setId()

public setId(int|null $id) : $this
Parameters
$id : int|null
Return values
$this

setInsertTime()

public setInsertTime(DateTime $insertTime) : $this
Parameters
$insertTime : DateTime
Return values
$this

setMeta()

public setMeta(string|null $meta) : $this
Parameters
$meta : string|null
Return values
$this

setPath()

public setPath(string $path) : $this
Parameters
$path : string
Return values
$this

setSerializedVariants()

public setSerializedVariants(string|null $serializedVariants) : $this
Parameters
$serializedVariants : string|null
Return values
$this

setThumbnailExtension()

public setThumbnailExtension(string|null $thumbnailExtension) : $this
Parameters
$thumbnailExtension : string|null
Return values
$this

setThumbnailsAttempts()

public setThumbnailsAttempts(int $thumbnailsAttempts) : $this
Parameters
$thumbnailsAttempts : int
Return values
$this

setThumbnailsGenerated()

public setThumbnailsGenerated(bool $thumbnailsGenerated) : $this
Parameters
$thumbnailsGenerated : bool
Return values
$this

setTranslations()

public setTranslations(Collection<int, TTranslation>|array<int, TTranslation> $translations) : $this
Parameters
$translations : Collection<int, TTranslation>|array<int, TTranslation>
Return values
$this

setUnserializedMeta()

public setUnserializedMeta(array<string, mixed> $meta) : $this
Parameters
$meta : array<string, mixed>
Return values
$this

setUnserializedVariants()

Saves variants as plain associative arrays (new format).

public setUnserializedVariants(array<int, array{name: string, maxWidth: int, maxHeight: int}> $unserializedVariants) : $this
Parameters
$unserializedVariants : array<int, array{name: string, maxWidth: int, maxHeight: int}>
Return values
$this

setUsageKey()

public setUsageKey(string|null $usageKey) : $this
Parameters
$usageKey : string|null
Return values
$this

setVariants()

public setVariants(string|null $variants) : $this
Parameters
$variants : string|null
Return values
$this

setVariantsAttempts()

public setVariantsAttempts(int $variantsAttempts) : $this
Parameters
$variantsAttempts : int
Return values
$this

buildVariant()

Builds an {@see AssetVariant} from a meta entry (URL + absolute path + dimensions); null for an invalid entry.

private buildVariant(string $name, mixed $entry) : AssetVariant|null
Parameters
$name : string
$entry : mixed
Return values
AssetVariant|null

describeVariantFile()

private describeVariantFile(mixed $variant, array<string, mixed> $metaVariants) : array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}|null
Parameters
$variant : mixed

variants item from the record (from JSON, shape not guaranteed)

$metaVariants : array<string, mixed>
Return values
array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}|null

getMetaVariants()

private getMetaVariants() : array<string, mixed>
Return values
array<string, mixed> —

meta.variants (folder => {width, height})

getSortedVariantEntries()

Returns variants with a width for sorting: downscaled variants ascending (real width, otherwise `maxWidth`, otherwise at the end of the downscaled ones), the original last; a tie goes to the smaller `maxWidth`, then record order.

private getSortedVariantEntries() : array<int, array{variant: array, file: array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}, width: int}>
Return values
array<int, array{variant: array, file: array{folder: string, variant: ?string, alias: ?string, width: ?int, height: ?int, maxWidth: int, original: bool}, width: int}>

getTraitsRecursive()

Walks the trait list recursively and collects nested traits too.

private static getTraitsRecursive(array<string, string> $traits) : array<string, string>
Parameters
$traits : array<string, string>
Return values
array<string, string>

intOf()

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

normalizeVariants()

Converts stored data (JSON / old serialize) to the variant shape; an item without a name is dropped (callers skipped it anyway), numbers and flags are cast, other keys stay.

private static normalizeVariants(array<string|int, mixed> $raw) : array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>
Parameters
$raw : array<string|int, mixed>
Return values
array<int, array{name: string, maxWidth: int, maxHeight: int, resizeFlags: array, useWatermark: bool, pathToWatermark?: string|null}>

resolveThumbnailFolder()

Returns the preview folder per {@see getThumbnailPath()}; null means no variant to use.

private resolveThumbnailFolder() : string|null
Return values
string|null

textOf()

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

Search results