Source of file AssetStore.php
Size: 11,798 Bytes - Last Modified: 2021-12-23T10:27:40+00:00
/var/www/docs.ssmods.com/process/src/src/Storage/AssetStore.php
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288 | <?php namespace SilverStripe\Assets\Storage; /** * Represents an abstract asset persistence layer. Acts as a backend to files. * * Asset storage is identified by the following values arranged into a tuple: * * - "Filename" - Descriptive path for a file, although not necessarily a physical location. This could include * custom directory names as a parent, as well as an extension. * - "Hash" - The SHA1 of the file. This means that multiple files with the same Filename could be * stored independently (depending on implementation) as long as they have different hashes. * When a variant is identified, this value will refer to the hash of the file it was generated * from, not the hash of the actual generated file. * - "Variant" - An arbitrary string (which should not contain filesystem invalid characters) used * to identify an asset which is a variant of an original. The asset storage backend has no knowledge * of the mechanism used to generate this file, and is up to user code to perform the actual * generation. An empty variant identifies this file as the original file. * * Write options have an additional $config parameter to provide additional options to the backend. * This is an associative array. Standard array options include 'visibility' and 'conflict'. * * 'conflict' config option determines the conflict resolution mechanism. * When assets are stored in the backend, user code may request one of the following conflict resolution * mechanisms: * * - CONFLICT_OVERWRITE - If there is an existing file with this tuple, overwrite it. * - CONFLICT_RENAME - If there is an existing file with this tuple, pick a new Filename for it and return it. * This option is not allowed for use when storing variants, which should not modify the underlying * Filename tuple value. * - CONFLICT_USE_EXISTING - If there is an existing file with this tuple, return the tuple for the * existing file instead. * - CONFLICT_EXCEPTION - If there is an existing file with this tuple, throw an exception. * * 'visibility' config option determines whether the file should be marked as publicly visible. * This may be assigned to one of the below values: * * - VISIBILITY_PUBLIC: This file may be accessed by any public user. * - VISIBILITY_PROTECTED: This file must be whitelisted for individual users before being made available to that user. */ interface AssetStore { /** * Exception on file conflict */ const CONFLICT_EXCEPTION = 'exception'; /** * Overwrite on file conflict */ const CONFLICT_OVERWRITE = 'overwrite'; /** * Rename on file conflict. Rename rules will be determined by the backend. * * This option is not allowed for use when storing variants, which should not modify the underlying * Filename tuple value. */ const CONFLICT_RENAME = 'rename'; /** * On conflict, use existing file */ const CONFLICT_USE_EXISTING = 'existing'; /** * Protect this file */ const VISIBILITY_PROTECTED = 'protected'; /** * Make this file public */ const VISIBILITY_PUBLIC = 'public'; /** * Return list of feature capabilities of this backend as an array. * Array keys will be the options supported by $config, and the * values will be the list of accepted values for each option (or * true if any value is allowed). * * @return array */ public function getCapabilities(); /** * Assign a set of data to the backend * * @param string $data Raw binary/text content * @param string $filename Name for the resulting file * @param string $hash Hash of original file, if storing a variant. * @param string $variant Name of variant, if storing a variant. * @param array $config Write options. {@see AssetStore} * @return array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash * will be calculated from the given data. */ public function setFromString($data, $filename, $hash = null, $variant = null, $config = []); /** * Assign a local file to the backend. * * @param string $path Absolute filesystem path to file * @param string $filename Optional path to ask the backend to name as. * Will default to the filename of the $path, excluding directories. * @param string $hash Hash of original file, if storing a variant. * @param string $variant Name of variant, if storing a variant. * @param array $config Write options. {@see AssetStore} * @return array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash * will be calculated from the local file content. */ public function setFromLocalFile($path, $filename = null, $hash = null, $variant = null, $config = []); /** * Assign a stream to the backend * * @param resource $stream Streamable resource * @param string $filename Name for the resulting file * @param string $hash Hash of original file, if storing a variant. * @param string $variant Name of variant, if storing a variant. * @param array $config Write options. {@see AssetStore} * @return array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash * will be calculated from the raw stream. */ public function setFromStream($stream, $filename, $hash = null, $variant = null, $config = []); /** * Get contents of a given file * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @return string Data from the file. */ public function getAsString($filename, $hash, $variant = null); /** * Get a stream for this file * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @return resource Data stream */ public function getAsStream($filename, $hash, $variant = null); /** * Get the url for the file * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @param bool $grant Ensures that the url for any protected assets is granted for the current user. * If set to true, and the file is currently in protected mode, the asset store will ensure the * returned URL is accessible for the duration of the current session / user. * This will have no effect if the file is in published mode. * This will not grant access to users other than the owner of the current session. * @return string public url to this resource */ public function getAsURL($filename, $hash, $variant = null, $grant = true); /** * Get metadata for this file, if available * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @return array|null File information, or null if no metadata available */ public function getMetadata($filename, $hash, $variant = null); /** * Get mime type of this file * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @return string Mime type for this file */ public function getMimeType($filename, $hash, $variant = null); /** * Determine visibility of the given file * * @param string $filename * @param string $hash * @return string one of values defined by the constants VISIBILITY_PROTECTED or VISIBILITY_PUBLIC, or * null if the file does not exist */ public function getVisibility($filename, $hash); /** * Determine if a file exists with the given tuple * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. * If a variant is requested, this is the hash of the file before it was modified. * @param string|null $variant Optional variant string for this file * @return bool Flag as to whether the file exists */ public function exists($filename, $hash, $variant = null); /** * Delete a file (and all variants) identified by the given filename and hash * * @param string $filename * @param string $hash * @return bool Flag if a file was deleted */ public function delete($filename, $hash); /** * Rename a file (and all variants) to a new filename * * @param string $filename * @param string $hash * @param string $newName * @return string Updated Filename, or null if rename failed */ public function rename($filename, $hash, $newName); /** * Copy a file (and all variants) to a new filename * * @param string $filename * @param string $hash * @param string $newName * @return string|null Updated Filename, or null if copy failed */ public function copy($filename, $hash, $newName); /** * Publicly expose the file (and all variants) identified by the given filename and hash * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. */ public function publish($filename, $hash); /** * Protect a file (and all variants) from public access, identified by the given filename and hash. * * A protected file can be granted access to users on a per-session or per-user basis as response * to any future invocations of {@see grant()} or {@see getAsURL()} with $grant = true * * @param string $filename Filename (not including assets) * @param string $hash sha1 hash of the file content. */ public function protect($filename, $hash); /** * Ensures that access to the specified protected file is granted for the current user. * If this file is currently in protected mode, the asset store will ensure the * returned asset for the duration of the current session / user. * This will have no effect if the file is in published mode. * This will not grant access to users other than the owner of the current session. * Does not require a member to be logged in. * * @param string $filename * @param string $hash */ public function grant($filename, $hash); /** * Revoke access to the given file for the current user. * Note: This will have no effect if the given file is public * * @param string $filename * @param string $hash */ public function revoke($filename, $hash); /** * Check if the current user can view the given file. * * @param string $filename * @param string $hash * @return bool True if the file is verified and grants access to the current session / user. */ public function canView($filename, $hash); } |