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 Description
SORT_BY_MODIFIED
string "modified"
SORT_BY_SIZE
string "size"
SORT_BY_TITLE
string "title"
SORT_DIRECTION_ASC
string "asc"
SORT_DIRECTION_DESC
string "desc"

Properties

protected $cacheKey : string

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.

Parameters
Property Description
$originalPath
string

Specifies the original path of the folder.

$newPath
string

Specifies the new path of the folder.

Returns
bool

public deleteFiles (array $paths)

Deletes a file from the Library.

Parameters
Property Description
$paths
array

A list of file paths relative to the Library root to delete.

Returns
mixed

public deleteFolder (string $path)

Deletes a folder from the Library.

Parameters
Property Description
$path
string

Specifies the folder path relative to the Library root.

Returns
mixed

public exists (string $path) : bool

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

Parameters
Property Description
$path
string

Specifies the file path relative the the Library root.

Returns
bool

Returns TRUE if the file exists.

public findFiles (string $searchTerm, string $sortBy = "title", string $filter = null) : array

Finds files in the Library.

Parameters
Property Description
$searchTerm
string

Specifies the search term.

$sortBy
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

Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).

Returns
array

Returns an array of MediaLibraryItem objects.

public folderExists (string $path) : bool

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

Parameters
Property Description
$path
string

Specifies the folder path relative the the Library root.

Returns
bool

Returns TRUE if the folder exists.

public get (string $path) : string

Returns a file contents.

Parameters
Property Description
$path
string

Specifies the file path relative the the Library root.

Returns
string

Returns the file contents

public getCacheKey () : string

Get the cache key

Returns
string

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.

Parameters
Property Description
$path
string

Specifies a path to process.

Returns
string

Returns a processed string.

public getPathUrl (string $path) : string

Returns a public file URL.

Parameters
Property Description
$path
string

Specifies the file path relative the the Library root.

Returns
string

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
Illuminate\Filesystem\FilesystemAdapter

Returns the storage disk object.

public listAllDirectories (array $exclude = []) : array

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

Parameters
Property Description
$exclude
array

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

Returns
array

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.

Parameters
Property Description
$folder
string

Specifies the folder path relative the the Library root.

$sortBy
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

Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).

$ignoreFolders
boolean

Determines whether folders should be suppressed in the result list.

Returns
array

Returns an array of MediaLibraryItem objects.

public makeFolder (string $path) : bool

Creates a folder.

Parameters
Property Description
$path
string

Specifies the folder path.

Returns
bool

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

Moves a file to another location.

Parameters
Property Description
$oldPath
string

Specifies the original path of the file.

$newPath
string

Specifies the new path of the file.

$isRename
boolean
Returns
bool

public moveFolder (string $originalPath, string $newPath) : bool

Moves a folder.

Parameters
Property Description
$originalPath
string

Specifies the original path of the folder.

$newPath
string

Specifies the new path of the folder.

Returns
bool

public put (string $path, string $contents) : bool

Puts a file to the library.

Parameters
Property Description
$path
string

Specifies the file path relative the the Library root.

$contents
string

Specifies the file contents.

Returns
bool

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.

Returns
mixed

public setCacheKey (string $cacheKey)

Set the cache key

Parameters
Property Description
$cacheKey
string

The key to set as the cache key for this instance

Returns
mixed

public static url (string $file) : string

Helper that makes a URL for a media file.

Parameters
Property Description
$file
string
Returns
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.

Parameters
Property Description
$path
string

Specifies the path.

$normalizeOnly
boolean

Specifies if only the normalization, without validation should be performed.

Returns
string

Returns a normalized path.

protected filterItemList (array $itemList, string $filter)

Filters item list by file type.

Parameters
Property Description
$itemList
array

Specifies the item list to sort.

$filter
string

Determines the document type filtering preference. Supported values are 'image', 'video', 'audio', 'document' (see FILE_TYPE_XXX constants of MediaLibraryItem class).

Returns
mixed

protected generateRandomTmpFolderName ($location)

Parameters
Property Description
$location
mixed
Returns
mixed

protected getFolderItemCount (string $path) : int

Returns a number of items on a folder.

Parameters
Property Description
$path
string

Specifies the folder path relative to the storage disk root.

Returns
int

Returns the number of items in the folder.

protected getMediaRelativePath (string $path) : string

Returns path relative to the Library root folder.

Parameters
Property Description
$path
string

Specifies a path relative to the Library disk root.

Returns
string

Returns the updated path.

protected init ()

Initialize this singleton.

Returns
mixed

protected initLibraryItem (array $item, string $itemType) : mixed

Initializes a library item from file metadata and item type.

Parameters
Property Description
$item
array

Specifies the file metadata as returned by the storage adapter.

$itemType
string

Specifies the item type.

Returns
mixed

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).

Parameters
Property Description
$path
string

Specifies a path to check.

Returns
bool

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.

Parameters
Property Description
$path
string

Specifies a path to examine.

$words
array

A list of words to check against.

Returns
bool

protected scanFolderContents (string $fullFolderPath) : array

Fetches the contents of a folder from the Library.

Parameters
Property Description
$fullFolderPath
string

Specifies the folder path relative the the storage disk root.

Returns
array

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.

Parameters
Property Description
$itemList
array

Specifies the item list to sort.

$sortSettings
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].

Returns
mixed

public __clone ()

Inherited from Singleton
Returns
mixed

public __wakeup ()

Inherited from Singleton
Returns
mixed

public static final forgetInstance ($container = null) : void

Inherited from Singleton

Forget this singleton's instance if it exists

Parameters
Property Description
$container
mixed
Returns
void

public static final instance ($container = null) : static

Inherited from Singleton

Create a new instance of this singleton.

Parameters
Property Description
$container
mixed
Returns
static

protected final __construct ()

Inherited from Singleton

Constructor.

Returns
mixed
Copyright © 2024 Winter CMS