Assets

Type

Class

Namespace

craft\services

Inherits

craft\services\Assets » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

3.0.0

Assets service.

An instance of the service is available via Craft::$app->assets.

View source

Public Properties

Property	Description
behaviors	yii\base\Behavior – List of behaviors attached to this component.
currentUserTemporaryUploadFolder	craft\models\VolumeFolder
generatePendingTransformsViaQueue	boolean – Whether pending transforms should be generated by the queue
tempVolumeAndSubpath	array
totalAssets	integer
userTemporaryUploadFolder	craft\models\VolumeFolder

currentUserTemporaryUploadFolder

Type

craft\models\VolumeFolder

Default value

null

Access

Read-only

View source

generatePendingTransformsViaQueue

Type

boolean

Default value

true

Since

3.6.0

Whether pending transforms should be generated by the queue

View source

tempVolumeAndSubpath

Type

array

Default value

null

Access

Read-only

Since

3.7.39

View source

totalAssets

Type

integer

Default value

null

Access

Read-only

View source

userTemporaryUploadFolder

Type

craft\models\VolumeFolder

Default value

null

Access

Read-only

View source

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	Returns the fully qualified name of this class.
createFolder()	Save a volume folder.
createFolderQuery()	Returns a DbCommand object prepped for retrieving assets.
createTempAssetQuery()	Creates an asset query that is configured to return assets in the temporary upload location.
deleteFoldersByIds()	Deletes a folder by its ID.
detachBehavior()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
ensureFolderByFullPathAndVolume()	Ensures a folder entry exists in the DB for the full path and return its ID. Depending on the use, it's possible to also ensure a physical folder exists.
findFolder()	Finds the first folder that matches a given criteria.
findFolders()	Finds folders that match a given criteria.
foldersExist()	Returns whether any folders exist which match a given criteria.
getAllDescendantFolders()	Returns all of the folders that are descendants of a given folder.
getAssetById()	Returns a file by its ID.
getAssetPreviewHandler()	Returns the asset preview handler for a given asset, or null if the asset is not previewable.
getAssetUrl()	Returns the URL for an asset, possibly with a given transform applied.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getCurrentUserTemporaryUploadFolder()	Return the current user's temporary upload folder.
getFolderById()	Returns a folder by its ID.
getFolderByUid()	Returns a folder by its UID.
getFolderTreeByFolderId()	Returns the folder tree for assets by a folder ID.
getFolderTreeByVolumeIds()	Returns the folder tree for assets by volume IDs
getIconPath()	Returns a generic file extension icon path, that can be used as a fallback for assets that don't have a normal thumbnail.
getNameReplacementInFolder()	Find a replacement for a filename
getRootFolderByVolumeId()	Returns the root folder for a given volume ID.
getTempVolumeAndSubpath()	Returns the temporary volume and subpath, if set.
getThumbPath()	Returns the control panel thumbnail path for a given asset.
getThumbUrl()	Returns the control panel thumbnail URL for a given asset.
getTotalAssets()	Gets the total number of assets that match a given criteria.
getTotalFolders()	Gets the total number of folders that match a given criteria.
getUserTemporaryUploadFolder()	Returns the given user's temporary upload folder.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes the object.
moveAsset()	Move or rename an asset.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
renameFolderById()	Renames a folder by its ID.
replaceAssetFile()	Replace an asset's file.
storeFolderRecord()	Store a folder by model
trigger()	Triggers an event.

createFolder()

Save a volume folder.

View source

Arguments

• $folder (craft\models\VolumeFolder)
• $indexExisting (boolean) – Set to true to just index the folder if it already exists on volume.

Throws

• craft\errors\AssetConflictException
  if a folder already exists with such a name
• yii\base\InvalidArgumentException
  if $folder doesn’t have a parent
• craft\errors\VolumeObjectExistsException
  if the file actually exists on the volume, but on in the index

createFolderQuery()

Since

3.8.0

Returns a DbCommand object prepped for retrieving assets.

View source

Returns

craft\db\Query

createTempAssetQuery()

Since

3.7.39

Creates an asset query that is configured to return assets in the temporary upload location.

View source

Returns

craft\elements\db\AssetQuery

Throws

• yii\base\InvalidConfigException
  If the temp volume is invalid

deleteFoldersByIds()

Deletes a folder by its ID.

View source

Arguments

• $folderIds (array, integer)
• $deleteDir (boolean) – Should the volume directory be deleted along the record, if applicable. Defaults to true.

Throws

• craft\errors\VolumeException
  If deleting a single folder and it cannot be deleted.

ensureFolderByFullPathAndVolume()

Ensures a folder entry exists in the DB for the full path and return its ID. Depending on the use, it's possible to also ensure a physical folder exists.

View source

Arguments

• $fullPath (string) – The path to ensure the folder exists at.
• $volume (craft\base\VolumeInterface)
• $justRecord (boolean) – If set to false, will also make sure the physical folder exists on the volume.

Returns

integer

Throws

• craft\errors\VolumeException
  If the volume cannot be found.

findFolder()

Finds the first folder that matches a given criteria.

View source

Arguments

• $criteria (mixed)

Returns

craft\models\VolumeFolder, null

findFolders()

Finds folders that match a given criteria.

View source

Arguments

• $criteria (mixed)

Returns

craft\models\VolumeFolder[]

foldersExist()

Since

3.8.0

Returns whether any folders exist which match a given criteria.

View source

Arguments

• $criteria (mixed)

Returns

boolean

getAllDescendantFolders()

Returns all of the folders that are descendants of a given folder.

View source

Arguments

• $parentFolder (craft\models\VolumeFolder)
• $orderBy (string)
• $withParent (boolean) – Whether the parent folder should be included in the results
• $asTree (boolean) – Whether the folders should be returned hierarchically

Returns

craft\models\VolumeFolder[]

getAssetById()

Returns a file by its ID.

View source

Arguments

• $assetId (integer)
• $siteId (integer, null)

Returns

craft\elements\Asset, null

getAssetPreviewHandler()

Since

3.4.0

Returns the asset preview handler for a given asset, or null if the asset is not previewable.

View source

Arguments

• $asset (craft\elements\Asset)

Returns

craft\base\AssetPreviewHandlerInterface, null

getAssetUrl()

Returns the URL for an asset, possibly with a given transform applied.

View source

Arguments

• $asset (craft\elements\Asset)
• $transform (craft\models\AssetTransform, string, array, null)
• $generateNow (boolean, null) – Whether the transformed image should be generated immediately if it doesn’t exist. If null, it will be left up to the generateTransformsBeforePageLoad config setting.

Returns

string, null

getCurrentUserTemporaryUploadFolder()

DEPRECATED

Deprecated in 3.2.0. Use getUserTemporaryUploadFolder() instead.

Return the current user's temporary upload folder.

View source

Returns

craft\models\VolumeFolder

getFolderById()

Returns a folder by its ID.

View source

Arguments

• $folderId (integer)

Returns

craft\models\VolumeFolder, null

getFolderByUid()

Returns a folder by its UID.

View source

Arguments

• $folderUid (string)

Returns

craft\models\VolumeFolder, null

getFolderTreeByFolderId()

DEPRECATED

Deprecated in 3.8.0

Returns the folder tree for assets by a folder ID.

View source

Arguments

• $folderId (integer)

Returns

array

getFolderTreeByVolumeIds()

DEPRECATED

Deprecated in 3.8.0

Returns the folder tree for assets by volume IDs

View source

Arguments

• $allowedVolumeIds (array)
• $additionalCriteria (array) – Additional criteria for filtering the tree

Returns

array

getIconPath()

Returns a generic file extension icon path, that can be used as a fallback for assets that don't have a normal thumbnail.

View source

Arguments

• $asset (craft\elements\Asset)

Returns

string

getNameReplacementInFolder()

Find a replacement for a filename

View source

Arguments

• $originalFilename (string) – The original filename for which to find a replacement.
• $folderId (integer) – The folder in which to find the replacement

Returns

string – If a suitable filename replacement cannot be found.

Throws

• craft\errors\AssetLogicException
  If a suitable filename replacement cannot be found.
• yii\base\InvalidArgumentException
  if folder ID invalid

getRootFolderByVolumeId()

Returns the root folder for a given volume ID.

View source

Arguments

• $volumeId (integer) – The volume ID

Returns

craft\models\VolumeFolder, null – The root folder in that volume, or null if the volume doesn’t exist

getTempVolumeAndSubpath()

Since

3.7.39

Returns the temporary volume and subpath, if set.

View source

Returns

array

Throws

• yii\base\InvalidConfigException
  If the temp volume is invalid

getThumbPath()

Returns the control panel thumbnail path for a given asset.

See also getThumbUrl()View source

Arguments

• $asset (craft\elements\Asset) – Asset to return a thumb for
• $width (integer) – Width of the returned thumb
• $height (integer, null) – Height of the returned thumb (defaults to $width if null)
• $generate (boolean) – Whether to generate a thumb in none exists yet
• $fallbackToIcon (boolean) – Whether to return the path to a generic icon if a thumbnail can't be generated

Returns

string, false – Thumbnail path, or false if it doesn't exist and $generate is false

Throws

• yii\base\NotSupportedException
  if the asset can't have a thumbnail, and $fallbackToIcon is false

getThumbUrl()

Returns the control panel thumbnail URL for a given asset.

View source

Arguments

• $asset (craft\elements\Asset) – Asset to return a thumb for
• $width (integer) – Width of the returned thumb
• $height (integer, null) – Height of the returned thumb (defaults to $width if null)
• $generate (boolean) – Whether to generate a thumb in none exists yet
• $fallbackToIcon (boolean) – Whether to return the URL to a generic icon if a thumbnail can't be generated

Returns

string

Throws

• yii\base\NotSupportedException
  if the asset can't have a thumbnail, and $fallbackToIcon is false

getTotalAssets()

Gets the total number of assets that match a given criteria.

View source

Arguments

• $criteria (mixed)

Returns

integer

getTotalFolders()

Gets the total number of folders that match a given criteria.

View source

Arguments

• $criteria (mixed)

Returns

integer

getUserTemporaryUploadFolder()

Returns the given user's temporary upload folder.

If no user is provided, the currently-logged in user will be used (if there is one), or a folder named after the current session ID.

View source

Arguments

• $user (craft\elements\User, null)

Returns

craft\models\VolumeFolder

Throws

• craft\errors\VolumeException

moveAsset()

Move or rename an asset.

View source

Arguments

• $asset (craft\elements\Asset) – The asset whose file should be renamed
• $folder (craft\models\VolumeFolder) – The volume folder to move the asset to.
• $filename (string) – The new filename

Returns

boolean – Whether the asset was renamed successfully

Throws

• craft\errors\AssetLogicException
  if the asset’s volume is missing

renameFolderById()

Renames a folder by its ID.

View source

Arguments

• $folderId (integer)
• $newName (string)

Returns

string – The new folder name after cleaning it.

Throws

• craft\errors\AssetLogicException
  If the folder to be renamed can't be found or trying to rename the top folder.
• craft\errors\VolumeObjectExistsException
  If a folder already exists with the same name in the volume, but not in the index
• craft\errors\VolumeObjectNotFoundException
  If the folder to be renamed can't be found in the volume.
• craft\errors\AssetConflictException
  If a folder already exists with the same name

replaceAssetFile()

Replace an asset's file.

View source

Arguments

• $asset (craft\elements\Asset)
• $pathOnServer (string) – The path to the replacement file
• $filename (string) – The new filename to use

Throws

• craft\errors\FileException
  If there was a problem with the actual file.
• craft\errors\AssetLogicException
  If the asset to be replaced cannot be found.

storeFolderRecord()

Store a folder by model

View source

Arguments

• $folder (craft\models\VolumeFolder)

Events

EVENT_AFTER_REPLACE_ASSET

Type

craft\events\ReplaceAssetEvent

The event that is triggered after an asset is replaced.

---

EVENT_BEFORE_REPLACE_ASSET

Type

craft\events\ReplaceAssetEvent

The event that is triggered before an asset is replaced.

---

EVENT_GET_ASSET_THUMB_URL

Type

craft\events\GetAssetThumbUrlEvent

The event that is triggered when a thumbnail is being generated for an asset.

---

EVENT_GET_ASSET_URL

Type

craft\events\GetAssetUrlEvent

The event that is triggered when a transform is being generated for an asset.

---

EVENT_GET_THUMB_PATH

Type

craft\events\AssetThumbEvent

The event that is triggered when a thumbnail path is requested.

---

EVENT_REGISTER_PREVIEW_HANDLER

Type

craft\events\AssetPreviewEvent

Since

3.4.0

The event that is triggered when determining the preview handler for an asset.

---