AssetStore
interface AssetStore (View source)
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.
Constants
| CONFLICT_EXCEPTION |
Exception on file conflict |
| CONFLICT_OVERWRITE |
Overwrite on file conflict |
| CONFLICT_RENAME |
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. |
| CONFLICT_USE_EXISTING |
On conflict, use existing file |
| VISIBILITY_PROTECTED |
Protect this file |
| VISIBILITY_PUBLIC |
Make this file public |
Methods
Return list of feature capabilities of this backend as an array.
Assign a set of data to the backend
Assign a local file to the backend.
Assign a stream to the backend
Get contents of a given file
Get a stream for this file
Get the url for the file
Get metadata for this file, if available
Get mime type of this file
Determine visibility of the given file
Determine if a file exists with the given tuple
Delete a file (and all variants) identified by the given filename and hash
Rename a file (and all variants) to a new filename
Copy a file (and all variants) to a new filename
Publicly expose the file (and all variants) identified by the given filename and hash
Protect a file (and all variants) from public access, identified by the given filename and hash.
Ensures that access to the specified protected file is granted for the current user.
Revoke access to the given file for the current user.
Check if the current user can view the given file.
Details
array
getCapabilities()
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).
array
setFromString(string $data, string $filename, string $hash = null, string $variant = null, array $config = [])
Assign a set of data to the backend
array
setFromLocalFile(string $path, string $filename = null, string $hash = null, string $variant = null, array $config = [])
Assign a local file to the backend.
array
setFromStream(resource $stream, string $filename, string $hash = null, string $variant = null, array $config = [])
Assign a stream to the backend
string
getAsString(string $filename, string $hash, string|null $variant = null)
Get contents of a given file
resource
getAsStream(string $filename, string $hash, string|null $variant = null)
Get a stream for this file
string
getAsURL(string $filename, string $hash, string|null $variant = null, bool $grant = true)
Get the url for the file
array|null
getMetadata(string $filename, string $hash, string|null $variant = null)
Get metadata for this file, if available
string
getMimeType(string $filename, string $hash, string|null $variant = null)
Get mime type of this file
string
getVisibility(string $filename, string $hash)
Determine visibility of the given file
bool
exists(string $filename, string $hash, string|null $variant = null)
Determine if a file exists with the given tuple
bool
delete(string $filename, string $hash)
Delete a file (and all variants) identified by the given filename and hash
string
rename(string $filename, string $hash, string $newName)
Rename a file (and all variants) to a new filename
string|null
copy(string $filename, string $hash, string $newName)
Copy a file (and all variants) to a new filename
publish(string $filename, string $hash)
Publicly expose the file (and all variants) identified by the given filename and hash
protect(string $filename, string $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 \SilverStripe\Assets\Storage\grant()} or {see \SilverStripe\Assets\Storage\getAsURL()} with $grant = true
grant(string $filename, string $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.
revoke(string $filename, string $hash)
Revoke access to the given file for the current user.
Note: This will have no effect if the given file is public
bool
canView(string $filename, string $hash)
Check if the current user can view the given file.