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 UUID. |
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
# 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
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
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
# foldersExist()
- Since
- 4.4.0
Returns whether any folders exist which match a given criteria.
View source (opens new window)
Arguments
$criteria
(mixed
)
Returns
# 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$asTree
(boolean (opens new window)) – Whether the folders should be returned hierarchically
Returns
# 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
# 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 UUID.
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
# 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
# getIconPath()
DEPRECATED
Deprecated in 4.0.0. craft\helpers\Assets::iconSvg() or Asset::getThumbSvg()
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
# 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
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
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)$iconFallback
(boolean (opens new window)) – Whether an icon URL fallback should be returned as a fallback
Returns
string (opens new window), null (opens new window)
# getTotalAssets()
Gets the total number of assets that match a given criteria.
View source (opens new window)
Arguments
$criteria
(mixed
)
Returns
# getTotalFolders()
Gets the total number of folders that match a given criteria.
View source (opens new window)
Arguments
$criteria
(mixed
)
Returns
# 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
Returns
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
The event that is triggered after an asset is replaced.
# EVENT_BEFORE_REPLACE_ASSET
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.