MediaLibrary
Provides abstraction level for the Media Library operations.
class Cms\Classes\MediaLibrary
extends System\Classes\MediaLibraryImplements the library caching features and security checks.
Extends
| Class | Description |
|---|---|
MediaLibrary
|
Provides abstraction level for the Media Library operations. |
Traits
| Trait | Description |
|---|---|
Singleton
|
Singleton trait. |
Constants
| Constant | Type | Value | Description |
|---|---|---|---|
SORT_BY_MODIFIED
|
string |
"modified"
|
string
"modified"
|
SORT_BY_SIZE
|
string |
"size"
|
string
"size"
|
SORT_BY_TITLE
|
string |
"title"
|
string
"title"
|
SORT_DIRECTION_ASC
|
string |
"asc"
|
string
"asc"
|
SORT_DIRECTION_DESC
|
string |
"desc"
|
string
"desc"
|
Properties
inherited
protected
$cacheKey
:
string
= "system-media-library-contents"
Cache key
inherited protected $ignoreNames : array
Contains a list of files and directories to ignore. The list can be customized with cms.storage.media.ignore configuration option.
inherited protected $ignorePatterns : array
Contains a list of regex patterns to ignore in files and directories. The list can be customized with cms.storage.media.ignorePatterns configuration option.
inherited protected $storageDisk : mixed
A reference to the Media Library disk.
inherited protected $storageFolder : string
The root Library folder path.
inherited protected $storageFolderNameLength : int
Cache for the storage folder name length.
inherited protected $storagePath : string
Relative or absolute URL of the Library root folder.
Methods
protected init ()
Initialize this singleton.
inherited public __clone ()
inherited public __wakeup ()
inherited public copyFolder (string $originalPath, string $newPath) : bool
Copies a folder.
| Property | Type | Description |
|---|---|---|
| $originalPath | string |
string
Specifies the original path of the folder. |
| $newPath | string |
string
Specifies the new path of the folder. |
inherited public deleteFiles (array $paths)
Deletes a file from the Library.
| Property | Type | Description |
|---|---|---|
| $paths | array |
array
A list of file paths relative to the Library root to delete. |
inherited public deleteFolder (string $path)
Deletes a folder from the Library.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the folder path relative to the Library root. |
inherited public exists (string $path) : bool
Determines if a file with the specified path exists in the library.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the file path relative the the Library root. |
Returns TRUE if the file exists.
inherited
public
findFiles (string $searchTerm, string $sortBy = "title", string $filter = null)
: array
Finds files in the Library.
| Property | Type | Description |
|---|---|---|
| $searchTerm | string |
string
Specifies the search term. |
| $sortBy | string |
string
Determines the sorting preference. Supported values are 'title', 'size', 'lastModified' (see SORT_BY_XXX class constants), FALSE (to disable sorting), or an associative array with a 'by' key and a 'direction' key: ['by' => SORT_BY_XXX, 'direction' => SORT_DIRECTION_XXX]. |
| $filter | string |
string
Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class). |
Returns an array of MediaLibraryItem objects.
inherited public folderExists (string $path) : bool
Determines if a folder with the specified path exists in the library.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the folder path relative the the Library root. |
Returns TRUE if the folder exists.
inherited
public
static
final
forgetInstance ($container = null)
: void
Forget this singleton's instance if it exists
| Property | Type | Description |
|---|---|---|
| $container | mixed |
mixed
|
inherited public get (string $path) : string
Returns a file contents.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the file path relative the the Library root. |
Returns the file contents
inherited public getCacheKey () : string
Get the cache key
The cache key to set as the cache key for this instance
inherited public getMediaPath (string $path) : string
Returns a file or folder path with the prefixed storage folder.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies a path to process. |
Returns a processed string.
inherited public getPathUrl (string $path) : string
Returns a public file URL.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the file path relative the the Library root. |
inherited public getStorageDisk () : Illuminate\Filesystem\FilesystemAdapter
Initializes and returns the Media Library disk.
This method should always be used instead of trying to access the $storageDisk property directly as initializing the disc requires communicating with the remote storage.
Returns the storage disk object.
inherited
public
static
final
instance ($container = null)
: static
Create a new instance of this singleton.
| Property | Type | Description |
|---|---|---|
| $container | mixed |
mixed
|
inherited
public
listAllDirectories (array $exclude = [])
: array
Returns a list of all directories in the Library, optionally excluding some of them.
| Property | Type | Description |
|---|---|---|
| $exclude | array |
array
A list of folders to exclude from the result list. The folder paths should be specified relative to the Library root. |
inherited
public
listFolderContents (string $folder = "\/", string $sortBy = "title", string $filter = null, boolean $ignoreFolders = false)
: array
Returns a list of folders and files in a Library folder.
| Property | Type | Description |
|---|---|---|
| $folder | string |
string
Specifies the folder path relative the the Library root. |
| $sortBy | string |
string
Determines the sorting preference. Supported values are 'title', 'size', 'lastModified' (see SORT_BY_XXX class constants), FALSE (to disable sorting), or an associative array with a 'by' key and a 'direction' key: ['by' => SORT_BY_XXX, 'direction' => SORT_DIRECTION_XXX]. |
| $filter | string |
string
Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class). |
| $ignoreFolders | boolean |
boolean
Determines whether folders should be suppressed in the result list. |
Returns an array of MediaLibraryItem objects.
inherited public makeFolder (string $path) : bool
Creates a folder.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the folder path. |
inherited
public
moveFile (string $oldPath, string $newPath, boolean $isRename = false)
: bool
Moves a file to another location.
| Property | Type | Description |
|---|---|---|
| $oldPath | string |
string
Specifies the original path of the file. |
| $newPath | string |
string
Specifies the new path of the file. |
| $isRename | boolean |
boolean
|
inherited public moveFolder (string $originalPath, string $newPath) : bool
Moves a folder.
| Property | Type | Description |
|---|---|---|
| $originalPath | string |
string
Specifies the original path of the folder. |
| $newPath | string |
string
Specifies the new path of the folder. |
inherited public put (string $path, string $contents) : bool
Puts a file to the library.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the file path relative the the Library root. |
| $contents | string |
string
Specifies the file contents. |
inherited public resetCache ()
Resets the Library cache.
The cache stores the library table of contents locally in order to optimize the performance when working with remote storages. The default cache TTL is 10 minutes. The cache is deleted automatically when an item is added, changed or deleted. This method allows to reset the cache forcibly.
inherited public setCacheKey (string $cacheKey)
Set the cache key
| Property | Type | Description |
|---|---|---|
| $cacheKey | string |
string
The key to set as the cache key for this instance |
inherited public static url (string $file) : string
Helper that makes a URL for a media file.
| Property | Type | Description |
|---|---|---|
| $file | string |
string
|
inherited
public
static
validatePath (string $path, boolean $normalizeOnly = false)
: string
Checks if file path doesn't contain any substrings that would pose a security threat.
Throws an exception if the path is not valid.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the path. |
| $normalizeOnly | boolean |
boolean
Specifies if only the normalization, without validation should be performed. |
Returns a normalized path.
inherited protected final __construct ()
Constructor.
inherited protected filterItemList (array $itemList, string $filter)
Filters item list by file type.
| Property | Type | Description |
|---|---|---|
| $itemList | array |
array
Specifies the item list to sort. |
| $filter | string |
string
Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class). |
inherited protected generateRandomTmpFolderName ($location)
| Property | Type | Description |
|---|---|---|
| $location | mixed |
mixed
|
inherited protected getFolderItemCount (string $path) : int
Returns a number of items on a folder.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies the folder path relative to the storage disk root. |
Returns the number of items in the folder.
inherited protected getMediaRelativePath (string $path) : string
Returns path relative to the Library root folder.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies a path relative to the Library disk root. |
Returns the updated path.
inherited protected initLibraryItem (array $item, string $itemType) : mixed
Initializes a library item from file metadata and item type.
| Property | Type | Description |
|---|---|---|
| $item | array |
array
Specifies the file metadata as returned by the storage adapter. |
| $itemType | string |
string
Specifies the item type. |
Returns the MediaLibraryItem object or NULL if the item is not visible.
inherited protected isVisible (string $path) : bool
Determines if the path should be visible (not ignored).
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies a path to check. |
Returns TRUE if the path is visible.
inherited protected pathMatchesSearch (string $path, array $words) : bool
Determines if file path contains all words form the search term.
| Property | Type | Description |
|---|---|---|
| $path | string |
string
Specifies a path to examine. |
| $words | array |
array
A list of words to check against. |
inherited protected scanFolderContents (string $fullFolderPath) : array
Fetches the contents of a folder from the Library.
| Property | Type | Description |
|---|---|---|
| $fullFolderPath | string |
string
Specifies the folder path relative the the storage disk root. |
Returns an array containing two elements - 'files' and 'folders', each is an array of MediaLibraryItem objects.
inherited protected sortItemList (array $itemList, mixed $sortSettings)
Sorts the item list by title, size or last modified date.
| Property | Type | Description |
|---|---|---|
| $itemList | array |
array
Specifies the item list to sort. |
| $sortSettings | mixed |
mixed
Determines the sorting preference. Supported values are 'title', 'size', 'lastModified' (see SORT_BY_XXX class constants) or an associative array with a 'by' key and a 'direction' key: ['by' => SORT_BY_XXX, 'direction' => SORT_DIRECTION_XXX]. |