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

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 = [])

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.

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

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

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

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 \SilverStripe\Assets\Storage\AssetStore}

Return Value

array

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

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

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 \SilverStripe\Assets\Storage\AssetStore}

Return Value

array

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

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

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 \SilverStripe\Assets\Storage\AssetStore}

Return Value

array

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

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.

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

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

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

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

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

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

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

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

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

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.

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

Parameters

string $filename

Filename (not including assets)

string $hash

sha1 hash of the file content.

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

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

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.