MediaLibrary
Provides abstraction level for the Media Library operations.
class System\Classes\MediaLibrary
Implements the library caching features and security checks.
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
protected
$cacheKey
:
string
= "system-media-library-contents"
Cache key
protected $ignoreNames : array
Contains a list of files and directories to ignore. The list can be customized with cms.storage.media.ignore configuration option.
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.
protected $storageDisk : mixed
A reference to the Media Library disk.
protected $storageFolder : string
The root Library folder path.
protected $storageFolderNameLength : int
Cache for the storage folder name length.
protected $storagePath : string
Relative or absolute URL of the Library root folder.
Methods
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. |
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. |
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. |
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.
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.
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.
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
public getCacheKey () : string
Get the cache key
The cache key to set as the cache key for this instance
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.
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. |
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.
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. |
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.
public makeFolder (string $path) : bool
Creates a folder.
Property | Type | Description |
---|---|---|
$path | string |
string
Specifies the folder path. |
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
|
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. |
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. |
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.
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 |
public static url (string $file) : string
Helper that makes a URL for a media file.
Property | Type | Description |
---|---|---|
$file | string |
string
|
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.
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). |
protected generateRandomTmpFolderName ($location)
Property | Type | Description |
---|---|---|
$location | mixed |
mixed
|
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.
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.
protected init ()
Initialize this singleton.
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.
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.
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. |
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.
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]. |
inherited public __clone ()
inherited public __wakeup ()
inherited
public
static
final
forgetInstance ($container = null
)
: void
Forget this singleton's instance if it exists
Property | Type | Description |
---|---|---|
$container | mixed |
mixed
|
inherited
public
static
final
instance ($container = null
)
: static
Create a new instance of this singleton.
Property | Type | Description |
---|---|---|
$container | mixed |
mixed
|
inherited protected final __construct ()
Constructor.
Extended by
Class | Description |
---|---|
MediaLibrary
|
Provides abstraction level for the Media Library operations. |