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

Protected Properties

protected string $cacheKey

protected string $storageUrl

storageUrl relative or absolute URL of the Library root folder.

protected mixed $storageDisk

storageDisk is a reference to the Media Library disk.

protected array $ignoreNames

ignoreNames contains a list of files and directories to ignore. The list can be customized with media.ignore_files configuration option.

protected array $ignorePatterns

ignorePatterns contains a list of regex patterns to ignore in files and directories. The list can be customized with media.ignore_patterns configuration option.

Public Methods

public __construct()

public __construct(): void

__construct this class

public copyFolder()

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

copyFolder copies an original path to a newly located path.

public deleteFiles()

public deleteFiles(array $paths): void

deleteFiles from the Library.

public deleteFolder()

public deleteFolder(string $path): void

deleteFolder from the Library.

public exists()

public exists(string $path): bool 

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

public findFile()

public findFile($path): Media\Classes\MediaLibraryItem|null 

findFile looks up a file and returns its MediaLibraryItem object

public findFiles()

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

findFiles in the Library.

public findFolder()

public findFolder($path): Media\Classes\MediaLibraryItem|null 

findFolder looks up a folder and returns its MediaLibraryItem object

public folderExists()

public folderExists(string $path): bool 

folderExists determines if a folder with the specified path exists in the library.

public get()

public get(string $path): string 

get returns a file contents.

public getCacheKey()

public getCacheKey(): string 

getCacheKey as the cache key for this instance

public getPathUrl()

public getPathUrl(string $path): string 

getPathUrl returns a public file URL.

public has()

public has(string $path): bool 

has checks for existence.

public static instance()

public static instance(): static 

instance creates a new instance of this singleton

public listAllDirectories()

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

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

public listFolderContents()

public listFolderContents(
    string $folder = '/',
    mixed $sortBy = 'title',
    string $filter = null,
    bool $ignoreFolders = false
): array 

listFolderContents returns a list of folders and files in a Library folder.

public makeFolder()

public makeFolder(string $path): bool 

makeFolder creates a folder.

public moveFile()

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

moveFile to another location.

public moveFolder()

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

moveFolder moves an original path to a newly located path.

public put()

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

put a file to the library.

public putFile()

public putFile(string $path, string $file): bool 

put a file to the library.

public resetCache()

public resetCache(): void

resetCache for 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()

public setCacheKey($cacheKey): void

setCacheKey as the cache key for this instance

public static url()

public static url(string $file): string 

url is a helper that makes a URL for a media file. Ideally the file should be passed as a string but it will try to deal with anything.

public static validatePath()

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

validatePath checks if file path doesn't contain any substrings that would pose a security threat. Returns a normalized path. Throws an exception if the path is not valid. An option is provided, if only normalization is needed without validation.

Protected Methods

protected filterItemList()

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

filterItemList by file type.

protected generateRandomTmpFolderName()

protected generateRandomTmpFolderName($location): void

protected getFolderItemCount()

protected getFolderItemCount(string $path): integer 

getFolderItemCount returns a number of items on a folder.

protected getStorageDisk()

protected getStorageDisk(): 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 initLibraryItem()

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

initLibraryItem from a path relative to the storage disk root and item type constant. Returns null if the item is not visible.

protected isLocalStorage()

protected isLocalStorage(): void

isLocalStorage returns true if the storage engine is local

protected isVisible()

protected isVisible(string $path): bool 

isVisible determines if the path should be visible and not ignored.

protected pathMatchesSearch()

protected pathMatchesSearch(string $path, array $words): bool 

pathMatchesSearch determines if file path contains all words form the search term.

protected scanFolderContents()

protected scanFolderContents(string $fullFolderPath): array 

scanFolderContents fetches the contents of a folder from the Library. The full 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()

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

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