Assets

Type

Class

Namespace

craft\services

Inherits

craft\services\Assets » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Since

3.0.0

Assets service.

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

View source (opens new window)

Public Properties

Property	Description
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
currentUserTemporaryUploadFolder	craft\models\VolumeFolder
tempVolumeAndSubpath	array (opens new window)
totalAssets	integer (opens new window)
userTemporaryUploadFolder	craft\models\VolumeFolder

currentUserTemporaryUploadFolder

Type

craft\models\VolumeFolder

Default value

null

View source (opens new window)

tempVolumeAndSubpath

Type

array (opens new window)

Default value

null

Access

Read-only

Since

3.7.39

View source (opens new window)

totalAssets

Type

integer (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

userTemporaryUploadFolder

Type

craft\models\VolumeFolder

Default value

null

Access

Read-only

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	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() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) 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() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
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 a list of hierarchical folders for the given volume IDs, indexed by volume ID.
getIconPath()	Returns a generic file extension icon path, that can be used as a fallback for assets that don't have a normal thumbnail.
getImagePreviewUrl()	Returns an image asset’s URL, scaled to fit within a max width and height.
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.
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() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
moveAsset()	Move or rename an asset.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	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() (opens new window)	Triggers an event.

createFolder()

Save a volume folder.

View source (opens new window)

Arguments

• $folder (craft\models\VolumeFolder)

Throws

• craft\errors\FsObjectExistsException
  if a folder already exists with such a name
• craft\errors\FsException
  if unable to create the directory on volume
• craft\errors\AssetException
  if invalid folder provided

createFolderQuery()

Since

4.4.0

Returns a DbCommand object prepped for retrieving assets.

View source (opens new window)

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 (opens new window)

Returns

craft\elements\db\AssetQuery

Throws

• yii\base\InvalidConfigException (opens new window)
  If the temp volume is invalid

deleteFoldersByIds()

Deletes a folder by its ID.

View source (opens new window)

Arguments

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

Throws

• yii\base\InvalidConfigException (opens new window)
  if the volume cannot be fetched from folder.

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 (opens new window)

Arguments

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

Returns

craft\models\VolumeFolder

Throws

• craft\errors\VolumeException
  if something went catastrophically wrong creating the folder.

findFolder()

Finds the first folder that matches a given criteria.

View source (opens new window)

Arguments

• $criteria (mixed)

Returns

craft\models\VolumeFolder, null (opens new window)

findFolders()

Finds folders that match a given criteria.

View source (opens new window)

Arguments

• $criteria (mixed)

Returns

craft\models\VolumeFolder[]

foldersExist()

Since

4.4.0

Returns whether any folders exist which match a given criteria.

View source (opens new window)

Arguments

• $criteria (mixed)

Returns

boolean (opens new window)

getAllDescendantFolders()

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

View source (opens new window)

Arguments

• $parentFolder (craft\models\VolumeFolder)
• $orderBy (string (opens new window))
• $withParent (boolean (opens new window)) – Whether the parent folder should be included in the results

Returns

craft\models\VolumeFolder[]

getAssetById()

Returns a file by its ID.

View source (opens new window)

Arguments

• $assetId (integer (opens new window))
• $siteId (integer (opens new window), null (opens new window))

Returns

craft\elements\Asset, null (opens new window)

getAssetPreviewHandler()

Since

3.4.0

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

View source (opens new window)

Arguments

• $asset (craft\elements\Asset)

Returns

craft\base\AssetPreviewHandlerInterface, null (opens new window)

getAssetUrl()

DEPRECATED

Deprecated in 4.0.0. craft\elements\Asset::getUrl() should be used instead.

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

View source (opens new window)

Arguments

• $asset (craft\elements\Asset)
• $transform (craft\models\ImageTransform, string (opens new window), array (opens new window), null (opens new window))

Returns

string (opens new window), null (opens new window)

Throws

• yii\base\InvalidConfigException (opens new window)

getFolderById()

Returns a folder by its ID.

View source (opens new window)

Arguments

• $folderId (integer (opens new window))

Returns

craft\models\VolumeFolder, null (opens new window)

getFolderByUid()

Returns a folder by its UID.

View source (opens new window)

Arguments

• $folderUid (string (opens new window))

Returns

craft\models\VolumeFolder, null (opens new window)

getFolderTreeByFolderId()

DEPRECATED

Deprecated in 4.4.0

Returns the folder tree for assets by a folder ID.

View source (opens new window)

Arguments

• $folderId (integer (opens new window))

Returns

array (opens new window)

getFolderTreeByVolumeIds()

DEPRECATED

Deprecated in 4.4.0d

Returns a list of hierarchical folders for the given volume IDs, indexed by volume ID.

View source (opens new window)

Arguments

• $volumeIds (array (opens new window))
• $additionalCriteria (array (opens new window)) – Additional criteria for filtering the tree

Returns

array (opens new window)

getIconPath()

DEPRECATED

Deprecated in 4.0.0. craft\helpers\Assets::iconPath() should be used instead.

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 (opens new window)

Arguments

• $asset (craft\elements\Asset)

Returns

string (opens new window)

getImagePreviewUrl()

Since

4.0.0

Returns an image asset’s URL, scaled to fit within a max width and height.

View source (opens new window)

Arguments

• $asset (craft\elements\Asset)
• $maxWidth (integer (opens new window))
• $maxHeight (integer (opens new window))

Returns

string (opens new window)

Throws

• yii\base\NotSupportedException (opens new window)
  if the asset’s volume doesn’t have a filesystem with public URLs

getNameReplacementInFolder()

Find a replacement for a filename

View source (opens new window)

Arguments

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

Returns

string (opens new window) – If a suitable filename replacement cannot be found.

Throws

• craft\errors\AssetOperationException
  If a suitable filename replacement cannot be found.
• yii\base\InvalidConfigException (opens new window)
• craft\errors\VolumeException

getRootFolderByVolumeId()

Returns the root folder for a given volume ID.

View source (opens new window)

Arguments

• $volumeId (integer (opens new window)) – The volume ID

Returns

craft\models\VolumeFolder, null (opens new window) – 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 (opens new window)

Returns

array (opens new window)

Throws

• yii\base\InvalidConfigException (opens new window)
  If the temp volume is invalid

getThumbUrl()

Returns the control panel thumbnail URL for a given asset.

View source (opens new window)

Arguments

• $asset (craft\elements\Asset) – Asset to return a thumb for
• $width (integer (opens new window)) – Width of the returned thumb
• $height (integer (opens new window), null (opens new window)) – Height of the returned thumb (defaults to $width if null)

Returns

string (opens new window)

getTotalAssets()

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

View source (opens new window)

Arguments

• $criteria (mixed)

Returns

integer (opens new window)

getTotalFolders()

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

View source (opens new window)

Arguments

• $criteria (mixed)

Returns

integer (opens new window)

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 (opens new window)

Arguments

• $user (craft\elements\User, null (opens new window))

Returns

craft\models\VolumeFolder

Throws

• craft\errors\VolumeException
  If no correct volume provided.

moveAsset()

Move or rename an asset.

View source (opens new window)

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 (opens new window)) – The new filename

Returns

boolean (opens new window) – Whether the asset was renamed successfully

renameFolderById()

Renames a folder by its ID.

View source (opens new window)

Arguments

• $folderId (integer (opens new window))
• $newName (string (opens new window))

Returns

string (opens new window) – The new folder name after cleaning it.

Throws

• craft\errors\AssetOperationException
  If the folder to be renamed can't be found or trying to rename the top folder.
• craft\errors\FsObjectExistsException
• craft\errors\FsObjectNotFoundException

replaceAssetFile()

Replace an asset's file.

View source (opens new window)

Arguments

• $asset (craft\elements\Asset)
• $pathOnServer (string (opens new window))
• $filename (string (opens new window))

storeFolderRecord()

Store a folder by model

View source (opens new window)

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_DEFINE_THUMB_URL

Type

craft\events\DefineAssetThumbUrlEvent

Since

4.0.0

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

See also getThumbUrl()

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.