1. interface
  2. SilverStripe
  3. \
  4. Assets
  5. \
  6. Storage
  7. \
  8. AssetStore

AssetStore

interface AssetStore

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

array
getCapabilities()

Return list of feature capabilities of this backend as an array.

array
setFromString(string $data, string $filename, string $hash = null, string $variant = null, array $config = array())

Assign a set of data to the backend

array
setFromLocalFile(string $path, string $filename = null, string $hash = null, string $variant = null, array $config = array())

Assign a local file to the backend.

array
setFromStream(resource $stream, string $filename, string $hash = null, string $variant = null, array $config = array())

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.

grant(string $filename, string $hash)

Ensures that access to the specified protected file is granted for the current user.

revoke(string $filename, string $hash)

Revoke access to the given file for the current user.

bool
canView(string $filename, string $hash)

Check if the current user can view the given file.

Details

at line 86
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).

Return Value

array

at line 99
array setFromString(string $data, string $filename, string $hash = null, string $variant = null, array $config = array())

Assign a set of data to the backend

Parameters

string $data Raw binary/text content
string $filename Name for the resulting file
string $hash Hash of original file, if storing a variant.
string $variant Name of variant, if storing a variant.
array $config Write options. {see AssetStore}

Return Value

array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash will be calculated from the given data.

at line 113
array setFromLocalFile(string $path, string $filename = null, string $hash = null, string $variant = null, array $config = array())

Assign a local file to the backend.

Parameters

string $path Absolute filesystem path to file
string $filename Optional path to ask the backend to name as. Will default to the filename of the $path, excluding directories.
string $hash Hash of original file, if storing a variant.
string $variant Name of variant, if storing a variant.
array $config Write options. {see AssetStore}

Return Value

array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash will be calculated from the local file content.

at line 126
array setFromStream(resource $stream, string $filename, string $hash = null, string $variant = null, array $config = array())

Assign a stream to the backend

Parameters

resource $stream Streamable resource
string $filename Name for the resulting file
string $hash Hash of original file, if storing a variant.
string $variant Name of variant, if storing a variant.
array $config Write options. {see AssetStore}

Return Value

array Tuple associative array (Filename, Hash, Variant) Unless storing a variant, the hash will be calculated from the raw stream.

at line 137
string getAsString(string $filename, string $hash, string|null $variant = null)

Get contents of a given file

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file

Return Value

string Data from the file.

at line 148
resource getAsStream(string $filename, string $hash, string|null $variant = null)

Get a stream for this file

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file

Return Value

resource Data stream

at line 164
string getAsURL(string $filename, string $hash, string|null $variant = null, bool $grant = true)

Get the url for the file

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file
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 Value

string public url to this resource

at line 175
array|null getMetadata(string $filename, string $hash, string|null $variant = null)

Get metadata for this file, if available

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file

Return Value

array|null File information, or null if no metadata available

at line 186
string getMimeType(string $filename, string $hash, string|null $variant = null)

Get mime type of this file

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file

Return Value

string Mime type for this file

at line 196
string getVisibility(string $filename, string $hash)

Determine visibility of the given file

Parameters

string $filename
string $hash

Return Value

string one of values defined by the constants VISIBILITY_PROTECTED or VISIBILITY_PUBLIC, or null if the file does not exist

at line 207
bool exists(string $filename, string $hash, string|null $variant = null)

Determine if a file exists with the given tuple

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content. If a variant is requested, this is the hash of the file before it was modified.
string|null $variant Optional variant string for this file

Return Value

bool Flag as to whether the file exists

at line 216
bool delete(string $filename, string $hash)

Delete a file (and all variants) identified by the given filename and hash

Parameters

string $filename
string $hash

Return Value

bool Flag if a file was deleted

at line 226
string rename(string $filename, string $hash, string $newName)

Rename a file (and all variants) to a new filename

Parameters

string $filename
string $hash
string $newName

Return Value

string Updated Filename, or null if rename failed

at line 236
string|null copy(string $filename, string $hash, string $newName)

Copy a file (and all variants) to a new filename

Parameters

string $filename
string $hash
string $newName

Return Value

string|null Updated Filename, or null if copy failed

at line 244
publish(string $filename, string $hash)

Publicly expose the file (and all variants) identified by the given filename and hash

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content.

at line 255
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 grant()} or {see getAsURL()} with $grant = true

Parameters

string $filename Filename (not including assets)
string $hash sha1 hash of the file content.

at line 268
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.

Parameters

string $filename
string $hash

at line 277
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

Parameters

string $filename
string $hash

at line 286
bool canView(string $filename, string $hash)

Check if the current user can view the given file.

Parameters

string $filename
string $hash

Return Value

bool True if the file is verified and grants access to the current session / user.