Class craft\services\Assets
- Inheritance
- craft\services\Assets » yii\base\Component » yii\base\BaseObject
- Implements
- yii\base\Configurable
- Available since version
- 3.0
- Source Code
- https://github.com/craftcms/cms/blob/master/src/services/Assets.php
Assets service.
An instance of the Assets service is globally accessible in Craft via Craft::$app->assets.
| Method | Description | Defined By |
|---|---|---|
__call() |
Calls the named method which is not a class method. | yii\base\BaseObject |
__clone() |
This method is called after the object is created by cloning an existing one. | yii\base\Component |
__construct() |
Constructor. | yii\base\BaseObject |
__get() |
Returns the value of an object property. | yii\base\BaseObject |
__isset() |
Checks if a property is set, i.e. defined and not null. | yii\base\BaseObject |
__set() |
Sets value of an object property. | yii\base\BaseObject |
__unset() |
Sets an object property to null. | yii\base\BaseObject |
attachBehavior() |
Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() |
Attaches a list of behaviors to the component. | yii\base\Component |
behaviors() |
Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() |
Returns a value indicating whether a property can be read. | yii\base\BaseObject |
canSetProperty() |
Returns a value indicating whether a property can be set. | yii\base\BaseObject |
className() |
Returns the fully qualified name of this class. | yii\base\BaseObject |
createFolder() |
Save an Asset folder. | craft\services\Assets |
deleteFoldersByIds() |
Deletes a folder by its ID. | craft\services\Assets |
detachBehavior() |
Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() |
Detaches all behaviors from the component. | yii\base\Component |
ensureBehaviors() |
Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
ensureFolderByFullPathAndVolume() |
Ensure a folder entry exists in the DB for the full path and return it's id. Depending on the use, it's possible to also ensure a physical folder exists. | craft\services\Assets |
findFolder() |
Finds the first folder that matches a given criteria. | craft\services\Assets |
findFolders() |
Finds folders that match a given criteria. | craft\services\Assets |
getAllDescendantFolders() |
Returns all of the folders that are descendants of a given folder. | craft\services\Assets |
getAssetById() |
Returns a file by its ID. | craft\services\Assets |
getAssetUrl() |
Returns the URL for an asset, possibly with a given transform applied. | craft\services\Assets |
getBehavior() |
Returns the named behavior object. | yii\base\Component |
getBehaviors() |
Returns all behaviors attached to this component. | yii\base\Component |
getCurrentUserTemporaryUploadFolder() |
Return the current user's temporary upload folder. | craft\services\Assets |
getFolderById() |
Returns a folder by its ID. | craft\services\Assets |
getFolderTreeByFolderId() |
Get the folder tree for Assets by a folder id. | craft\services\Assets |
getFolderTreeByVolumeIds() |
Get the folder tree for Assets by volume ids | craft\services\Assets |
getIconPath() |
Returns a generic file extension icon path, that can be used as a fallback for assets that don't have a normal thumbnail. | craft\services\Assets |
getNameReplacementInFolder() |
Find a replacement for a filename | craft\services\Assets |
getRootFolderByVolumeId() |
Returns the root folder for a given volume ID. | craft\services\Assets |
getThumbPath() |
Returns the CP thumbnail path for a given asset. | craft\services\Assets |
getThumbUrl() |
Returns the CP thumbnail URL for a given asset. | craft\services\Assets |
getTotalAssets() |
Gets the total number of assets that match a given criteria. | craft\services\Assets |
getTotalFolders() |
Gets the total number of folders that match a given criteria. | craft\services\Assets |
getUserTemporaryUploadFolder() |
Get the user's temporary upload folder. | craft\services\Assets |
hasEventHandlers() |
Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() |
Returns a value indicating whether a method is defined. | yii\base\BaseObject |
hasProperty() |
Returns a value indicating whether a property is defined. | yii\base\BaseObject |
init() |
Initializes the object. | yii\base\BaseObject |
moveAsset() |
Move or rename an Asset. | craft\services\Assets |
off() |
Detaches an existing event handler from this component. | yii\base\Component |
on() |
Attaches an event handler to an event. | yii\base\Component |
renameFolderById() |
Rename a folder by it's id. | craft\services\Assets |
replaceAssetFile() |
Replace an Asset's file. | craft\services\Assets |
storeFolderRecord() |
Store a folder by model | craft\services\Assets |
trigger() |
Triggers an event. | yii\base\Component |
| Event | Type | Description | Defined By |
|---|---|---|---|
EVENT_AFTER_REPLACE_ASSET |
\craft\services\AssetEvent | The event that is triggered after an asset is replaced. | craft\services\Assets |
EVENT_BEFORE_REPLACE_ASSET |
\craft\services\AssetEvent | The event that is triggered before an asset is replaced. | craft\services\Assets |
EVENT_GET_ASSET_THUMB_URL |
craft\events\GetAssetThumbUrlEvent | The event that is triggered when a thumbnail is being generated for an Asset. | craft\services\Assets |
EVENT_GET_ASSET_URL |
craft\events\GetAssetUrlEvent | The event that is triggered when a transform is being generated for an Asset. | craft\services\Assets |
EVENT_GET_THUMB_PATH |
craft\events\AssetThumbEvent | The event that is triggered when a thumbnail path is requested. | craft\services\Assets |
Method Details
createFolder()
public method
#
Save an Asset folder.
public void createFolder ( craft\models\VolumeFolder $folder, \craft\services\bool $indexExisting = false )$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 |
|---|---|---|
| throws | yii\base\InvalidArgumentException | if $folder doesn’t have a parent |
| throws | craft\errors\VolumeObjectExistsException | if the file actually exists on the volume, but on in the index |
deleteFoldersByIds()
public method
#
Deletes a folder by its ID.
public void deleteFoldersByIds ( $folderIds, \craft\services\bool $deleteDir = true )$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()
public method
#
Ensure a folder entry exists in the DB for the full path and return it's id. Depending on the use, it's possible to also ensure a physical folder exists.
public integer ensureFolderByFullPathAndVolume ( \craft\services\string $fullPath, craft\base\Volume $volume, \craft\services\bool $justRecord = true )$fullPath |
string | The path to ensure the folder exists at. |
$volume |
craft\base\Volume | |
$justRecord |
boolean | If set to false, will also make sure the physical folder exists on Volume. |
| throws | craft\errors\VolumeException | If the volume cannot be found. |
|---|
findFolder()
public method
#
Finds the first folder that matches a given criteria.
public craft\models\VolumeFolder, null findFolder ( $criteria = null )$criteria |
mixed |
findFolders()
public method
#
Finds folders that match a given criteria.
public craft\models\VolumeFolder[] findFolders ( $criteria = null )$criteria |
mixed |
getAllDescendantFolders()
public method
#
Returns all of the folders that are descendants of a given folder.
public array getAllDescendantFolders ( craft\models\VolumeFolder $parentFolder, \craft\services\string $orderBy = 'path' )$parentFolder |
craft\models\VolumeFolder | |
$orderBy |
string |
getAssetById()
public method
#
Returns a file by its ID.
public craft\elements\Asset, null getAssetById ( \craft\services\int $assetId, \craft\services\int $siteId = null )$assetId |
integer | |
$siteId |
integer, null |
getAssetUrl()
public method
#
Returns the URL for an asset, possibly with a given transform applied.
public string, null getAssetUrl ( craft\elements\Asset $asset, $transform = null, \craft\services\bool $generateNow = null )$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. Default is null, meaning it
will be left up to the generateTransformsBeforePageLoad sconfig setting.
|
getCurrentUserTemporaryUploadFolder()
public method
#
Return the current user's temporary upload folder.
public craft\models\VolumeFolder getCurrentUserTemporaryUploadFolder ( )
getFolderById()
public method
#
Returns a folder by its ID.
public craft\models\VolumeFolder, null getFolderById ( \craft\services\int $folderId )$folderId |
integer |
getFolderTreeByFolderId()
public method
#
Get the folder tree for Assets by a folder id.
public array getFolderTreeByFolderId ( \craft\services\int $folderId )$folderId |
integer |
getFolderTreeByVolumeIds()
public method
#
Get the folder tree for Assets by volume ids
public array getFolderTreeByVolumeIds ( $allowedVolumeIds, array $additionalCriteria = [] )$allowedVolumeIds |
array | |
$additionalCriteria |
array | Additional criteria for filtering the tree |
getIconPath()
public method
#
Returns a generic file extension icon path, that can be used as a fallback for assets that don't have a normal thumbnail.
public string getIconPath ( craft\elements\Asset $asset )$asset |
craft\elements\Asset |
getNameReplacementInFolder()
public method
#
Find a replacement for a filename
public string getNameReplacementInFolder ( \craft\services\string $originalFilename, \craft\services\int $folderId )$originalFilename |
string | The original filename for which to find a replacement. |
$folderId |
integer | THe folder in which to find the replacement |
| return | string | If a suitable filename replacement cannot be found. |
|---|---|---|
| throws | craft\errors\AssetLogicException | If a suitable filename replacement cannot be found. |
| throws | yii\base\InvalidArgumentException | If $folderId is invalid |
getRootFolderByVolumeId()
public method
#
Returns the root folder for a given volume ID.
public craft\models\VolumeFolder, null getRootFolderByVolumeId ( \craft\services\int $volumeId )$volumeId |
integer | The volume ID |
| return | craft\models\VolumeFolder, null | The root folder in that volume, or null if the volume doesn’t exist |
|---|
getThumbPath()
public method
#
Returns the CP thumbnail path for a given asset.
See also getThumbUrl().
public string, false getThumbPath ( craft\elements\Asset $asset, \craft\services\int $width, \craft\services\int $height = null, \craft\services\bool $generate = true, \craft\services\bool $fallbackToIcon = true )$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 |
| return | 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()
public method
#
Returns the CP thumbnail URL for a given asset.
See also craft\elements\Asset::getThumbUrl().
public string getThumbUrl ( craft\elements\Asset $asset, \craft\services\int $width, \craft\services\int $height = null, \craft\services\bool $generate = false, \craft\services\bool $fallbackToIcon = true )$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 |
| throws | yii\base\NotSupportedException | if the asset can't have a thumbnail, and $fallbackToIcon is false
|
|---|
getTotalAssets()
public method
#
Gets the total number of assets that match a given criteria.
public integer getTotalAssets ( $criteria = null )$criteria |
mixed |
getTotalFolders()
public method
#
Gets the total number of folders that match a given criteria.
public integer getTotalFolders ( $criteria )$criteria |
mixed |
getUserTemporaryUploadFolder()
public method
#
Get the user's temporary upload folder.
public craft\models\VolumeFolder getUserTemporaryUploadFolder ( craft\elements\User $userModel = null )$userModel |
craft\elements\User, null |
moveAsset()
public method
#
Move or rename an Asset.
public boolean moveAsset ( craft\elements\Asset $asset, craft\models\VolumeFolder $folder, \craft\services\string $filename = '' )$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 |
| return | boolean | Whether the asset was renamed successfully |
|---|---|---|
| throws | craft\errors\AssetLogicException | if the asset’s volume is missing |
renameFolderById()
public method
#
Rename a folder by it's id.
public string renameFolderById ( \craft\services\int $folderId, \craft\services\string $newName )$folderId |
integer | |
$newName |
string | |
| return | string | The new folder name after cleaning it. |
|---|---|---|
| throws | craft\errors\AssetConflictException | If a folder already exists with such name in Assets Index |
| throws | craft\errors\AssetLogicException | If the folder to be renamed can't be found or trying to rename the top folder. |
| throws | craft\errors\VolumeObjectExistsException | If a folder already exists with such name in the Volume, but not in Index |
| throws | craft\errors\VolumeObjectNotFoundException | If the folder to be renamed can't be found in the Volume. |
replaceAssetFile()
public method
#
Replace an Asset's file.
Replace an Asset's file by it's id, a local file and the filename to use.
public void replaceAssetFile ( craft\elements\Asset $asset, \craft\services\string $pathOnServer, \craft\services\string $filename )$asset |
craft\elements\Asset | |
$pathOnServer |
string | |
$filename |
string | |
| throws | craft\errors\FileException | If there was a problem with the actual file. |
|---|---|---|
| throws | craft\errors\AssetLogicException | If the Asset to be replaced cannot be found. |
storeFolderRecord()
public method
#
Store a folder by model
public void storeFolderRecord ( craft\models\VolumeFolder $folder )$folder |
craft\models\VolumeFolder |
Event Details
EVENT_AFTER_REPLACE_ASSET
event of type \craft\services\AssetEvent
#
The event that is triggered after an asset is replaced.
EVENT_BEFORE_REPLACE_ASSET
event of type \craft\services\AssetEvent
#
The event that is triggered before an asset is replaced.
EVENT_GET_ASSET_THUMB_URL
event of type craft\events\GetAssetThumbUrlEvent
#
The event that is triggered when a thumbnail is being generated for an Asset.
EVENT_GET_ASSET_URL
event of type craft\events\GetAssetUrlEvent
#
The event that is triggered when a transform is being generated for an Asset.
EVENT_GET_THUMB_PATH
event of type craft\events\AssetThumbEvent
#
The event that is triggered when a thumbnail path is requested.