System\Classes\MediaLibrary

Source: ~/modules/system/classes/MediaLibrary.php

Provides abstraction level for the Media Library operations. Implements the library caching features and security checks.

Protected properties

protected string $cacheKey

Cache key

protected string $storagePath

Relative or absolute URL of the Library root folder.

protected string $storageFolder

The root Library folder path.

protected mixed $storageDisk

A reference to the Media Library disk.

protected array $ignoreNames

Contains a list of files and directories to ignore. The list can be customized with cms.storage.media.ignore configuration option.

protected array $ignorePatterns

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 int $storageFolderNameLength

Cache for the storage folder name length.

protected static $instance

Public methods

public void __clone()

public void __wakeup()

public boolean copyFolder(string $originalPath, string $newPath)

Copies a folder.

Parameters

• string $originalPath - Specifies the original path of the folder.
• string $newPath - Specifies the new path of the folder.

public void deleteFiles(array $paths)

Deletes a file from the Library.

Parameters

• array $paths - A list of file paths relative to the Library root to delete.

public void deleteFolder(string $path)

Deletes a folder from the Library.

Parameters

• string $path - Specifies the folder path relative to the Library root.

public boolean exists(string $path)

Determines if a file with the specified path exists in the library.

Parameters

• string $path - Specifies the file path relative the the Library root.

public array findFiles(string $searchTerm, mixed $sortBy='title', string $filter=NULL)

Finds files in the Library.

Parameters

• string $searchTerm - Specifies the search term.
• mixed $sortBy - 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].
• string $filter - Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).

public boolean folderExists(string $path)

Determines if a folder with the specified path exists in the library.

Parameters

• string $path - Specifies the folder path relative the the Library root.

public static void forgetInstance()

Forget this singleton's instance if it exists

public string get(string $path)

Returns a file contents.

Parameters

• string $path - Specifies the file path relative the the Library root.

public string getCacheKey()

Get the cache key

public string getPathUrl(string $path)

Returns a public file URL.

Parameters

• string $path - Specifies the file path relative the the Library root.

public static void instance()

Create a new instance of this singleton.

public array listAllDirectories(array $exclude=array())

Returns a list of all directories in the Library, optionally excluding some of them.

Parameters

• array $exclude - A list of folders to exclude from the result list. The folder paths should be specified relative to the Library root.

public array listFolderContents(string $folder='/', mixed $sortBy='title', string $filter=NULL, boolean $ignoreFolders=false)

Returns a list of folders and files in a Library folder.

Parameters

• string $folder - Specifies the folder path relative the the Library root.
• mixed $sortBy - 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].
• string $filter - Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).
• boolean $ignoreFolders - Determines whether folders should be suppressed in the result list.

public boolean makeFolder(string $path)

Creates a folder.

Parameters

• string $path - Specifies the folder path.

public boolean moveFile(string $oldPath, string $newPath, $isRename=false)

Moves a file to another location.

Parameters

• string $oldPath - Specifies the original path of the file.
• string $newPath - Specifies the new path of the file.
• $isRename

public boolean moveFolder(string $originalPath, string $newPath)

Moves a folder.

Parameters

• string $originalPath - Specifies the original path of the folder.
• string $newPath - Specifies the new path of the folder.

public boolean put(string $path, string $contents)

Puts a file to the library.

Parameters

• string $path - Specifies the file path relative the the Library root.
• string $contents - Specifies the file contents.

public void 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 void setCacheKey(string $cacheKey)

Set the cache key

Parameters

• string $cacheKey - The key to set as the cache key for this instance

public static string url(string $file)

Helper that makes a URL for a media file.

Parameters

• string $file

public static string validatePath(string $path, boolean $normalizeOnly=false)

Checks if file path doesn't contain any substrings that would pose a security threat. Throws an exception if the path is not valid.

Parameters

• string $path - Specifies the path.
• boolean $normalizeOnly - Specifies if only the normalization, without validation should be performed.

Protected methods

protected void __construct()

Constructor.

protected void filterItemList(array &$itemList, string $filter)

Filters item list by file type.

Parameters

• array &$itemList - Specifies the item list to sort.
• string $filter - Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).

protected void generateRandomTmpFolderName($location)

Parameters

• $location

protected integer getFolderItemCount(string $path)

Returns a number of items on a folder.

Parameters

• string $path - Specifies the folder path relative to the storage disk root.

protected string getMediaPath(string $path)

Returns a file or folder path with the prefixed storage folder.

Parameters

• string $path - Specifies a path to process.

protected string getMediaRelativePath(string $path)

Returns path relative to the Library root folder.

Parameters

• string $path - Specifies a path relative to the Library disk root.

protected mixed getStorageDisk()

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.

protected void init()

Initialize this singleton.

protected mixed initLibraryItem(string $path, string $itemType)

Initializes a library item from a path and item type.

Parameters

• string $path - Specifies the item path relative to the storage disk root.
• string $itemType - Specifies the item type.

protected boolean isVisible(string $path)

Determines if the path should be visible (not ignored).

Parameters

• string $path - Specifies a path to check.

protected boolean pathMatchesSearch(string $path, array $words)

Determines if file path contains all words form the search term.

Parameters

• string $path - Specifies a path to examine.
• array $words - A list of words to check against.

protected array scanFolderContents(string $fullFolderPath)

Fetches the contents of a folder from the Library.

Parameters

• string $fullFolderPath - Specifies the folder path relative the the storage disk root.

protected void sortItemList(array &$itemList, mixed $sortSettings)

Sorts the item list by title, size or last modified date.

Parameters

• array &$itemList - Specifies the item list to sort.
• mixed $sortSettings - 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].