MediaLibrary
        
        Provides abstraction level for the Media Library operations.
    
    
 class System\Classes\MediaLibraryImplements 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. |