Documentation

MediaLibrary
in package

october

system

Uses Singleton

Provides abstraction level for the Media Library operations.

Implements the library caching features and security checks.

SORT_BY_MODIFIED


    public
    mixed
    SORT_BY_MODIFIED
    = 'modified'

SORT_BY_SIZE


    public
    mixed
    SORT_BY_SIZE
    = 'size'

SORT_BY_TITLE


    public
    mixed
    SORT_BY_TITLE
    = 'title'

SORT_DIRECTION_ASC


    public
    mixed
    SORT_DIRECTION_ASC
    = 'asc'

SORT_DIRECTION_DESC


    public
    mixed
    SORT_DIRECTION_DESC
    = 'desc'

$cacheKey


    protected
        string
    $cacheKey
     = 'system-media-library-contents'

Cache key

$ignoreNames


    protected
        array<string|int, mixed>
    $ignoreNames

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

$ignorePatterns


    protected
        array<string|int, mixed>
    $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.

$instance


    protected
    static    mixed
    $instance

$storageDisk


    protected
        mixed
    $storageDisk

A reference to the Media Library disk.

$storageFolder


    protected
        string
    $storageFolder

The root Library folder path.

$storageFolderNameLength


    protected
        int
    $storageFolderNameLength

Cache for the storage folder name length.

$storagePath


    protected
        string
    $storagePath

Relative or absolute URL of the Library root folder.

__clone()


    public
                __clone() : mixed

Return values

mixed —

__wakeup()


    public
                __wakeup() : mixed

Return values

mixed —

copyFolder()

Copies a folder.


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

Parameters

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

Return values

bool —

deleteFiles()

Deletes a file from the Library.


    public
                deleteFiles(array<string|int, mixed> $paths) : mixed

Parameters

$paths : array<string|int, mixed>: A list of file paths relative to the Library root to delete.

Return values

mixed —

deleteFolder()

Deletes a folder from the Library.


    public
                deleteFolder(string $path) : mixed

Parameters

$path : string: Specifies the folder path relative to the Library root.

Return values

mixed —

exists()

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


    public
                exists(string $path) : bool

Parameters

$path : string: Specifies the file path relative the the Library root.

Return values

bool —

Returns TRUE if the file exists.

findFiles()

Finds files in the Library.


    public
                findFiles(string $searchTerm[, mixed $sortBy = 'title' ][, string $filter = null ]) : array<string|int, mixed>

Parameters

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

Return values

array<string|int, mixed> —

Returns an array of MediaLibraryItem objects.

folderExists()

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


    public
                folderExists(string $path) : bool

Parameters

$path : string: Specifies the folder path relative the the Library root.

Return values

bool —

Returns TRUE if the folder exists.

forgetInstance()

Forget this singleton's instance if it exists


    public
        final    static    forgetInstance() : mixed

Return values

mixed —

get()

Returns a file contents.


    public
                get(string $path) : string

Parameters

$path : string: Specifies the file path relative the the Library root.

Return values

string —

Returns the file contents

getCacheKey()

Get the cache key


    public
                getCacheKey() : string

Return values

string —

The cache key to set as the cache key for this instance

getPathUrl()

Returns a public file URL.


    public
                getPathUrl(string $path) : string

Parameters

$path : string: Specifies the file path relative the the Library root.

Return values

string —

instance()

Create a new instance of this singleton.


    public
        final    static    instance() : mixed

Return values

mixed —

listAllDirectories()

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


    public
                listAllDirectories([array<string|int, mixed> $exclude = [] ]) : array<string|int, mixed>

Parameters

$exclude : array<string|int, mixed> = []: A list of folders to exclude from the result list. The folder paths should be specified relative to the Library root.

Return values

array<string|int, mixed> —

listFolderContents()

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


    public
                listFolderContents([string $folder = '/' ][, mixed $sortBy = 'title' ][, string $filter = null ][, bool $ignoreFolders = false ]) : array<string|int, mixed>

Parameters

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

Return values

array<string|int, mixed> —

Returns an array of MediaLibraryItem objects.

makeFolder()

Creates a folder.


    public
                makeFolder(string $path) : bool

Parameters

$path : string: Specifies the folder path.

Return values

bool —

moveFile()

Moves a file to another location.


    public
                moveFile(string $oldPath, string $newPath[, mixed $isRename = false ]) : bool

Parameters

$oldPath : string: Specifies the original path of the file.
$newPath : string: Specifies the new path of the file.
$isRename : mixed = false

Return values

bool —

moveFolder()

Moves a folder.


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

Parameters

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

Return values

bool —

put()

Puts a file to the library.


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

Parameters

$path : string: Specifies the file path relative the the Library root.
$contents : string: Specifies the file contents.

Return values

bool —

resetCache()

Resets the Library cache.


    public
                resetCache() : mixed

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.

Return values

mixed —

setCacheKey()

Set the cache key


    public
                setCacheKey(string $cacheKey) : mixed

Parameters

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

Return values

mixed —

url()

Helper that makes a URL for a media file.


    public
            static    url(string $file) : string

Parameters

$file : string

Return values

string —

validatePath()

Checks if file path doesn't contain any substrings that would pose a security threat.


    public
            static    validatePath(string $path[, bool $normalizeOnly = false ]) : string

Throws an exception if the path is not valid.

Parameters

$path : string: Specifies the path.
$normalizeOnly : bool = false: Specifies if only the normalization, without validation should be performed.

Return values

string —

Returns a normalized path.

__construct()

Constructor.


    protected
        final        __construct() : mixed

Return values

mixed —

filterItemList()

Filters item list by file type.


    protected
                filterItemList(array<string|int, mixed> &$itemList, string $filter) : mixed

Parameters

$itemList : array<string|int, mixed>: 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).

Return values

mixed —

generateRandomTmpFolderName()


    protected
                generateRandomTmpFolderName(mixed $location) : mixed

Parameters

$location : mixed

Return values

mixed —

getFolderItemCount()

Returns a number of items on a folder.


    protected
                getFolderItemCount(string $path) : int

Parameters

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

Return values

int —

Returns the number of items in the folder.

getMediaPath()

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


    protected
                getMediaPath(string $path) : string

Parameters

$path : string: Specifies a path to process.

Return values

string —

Returns a processed string.

getMediaRelativePath()

Returns path relative to the Library root folder.


    protected
                getMediaRelativePath(string $path) : string

Parameters

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

Return values

string —

Returns the updated path.

getStorageDisk()

Initializes and returns the Media Library disk.


    protected
                getStorageDisk() : mixed

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.

Return values

mixed —

Returns the storage disk object.

init()

Initialize this singleton.


    protected
                init() : mixed

Return values

mixed —

initLibraryItem()

Initializes a library item from file metadata and item type.


    protected
                initLibraryItem(array<string|int, mixed> $item, string $itemType) : mixed

Parameters

$item : array<string|int, mixed>: Specifies the file metadata as returned by the storage adapter.
$itemType : string: Specifies the item type.

Return values

mixed —

Returns the MediaLibraryItem object or NULL if the item is not visible.

isVisible()

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


    protected
                isVisible(string $path) : bool

Parameters

$path : string: Specifies a path to check.

Return values

bool —

Returns TRUE if the path is visible.

pathMatchesSearch()

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


    protected
                pathMatchesSearch(string $path, array<string|int, mixed> $words) : bool

Parameters

$path : string: Specifies a path to examine.
$words : array<string|int, mixed>: A list of words to check against.

Return values

bool —

scanFolderContents()

Fetches the contents of a folder from the Library.


    protected
                scanFolderContents(string $fullFolderPath) : array<string|int, mixed>

Parameters

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

Return values

array<string|int, mixed> —

Returns an array containing two elements - 'files' and 'folders', each is an array of MediaLibraryItem objects.

sortItemList()

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


    protected
                sortItemList(array<string|int, mixed> &$itemList, mixed $sortSettings) : mixed

Parameters

$itemList : array<string|int, mixed>: 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].

Return values

mixed —