DriverInterface
in
This class determines what behaviors a blob storage needs to define to be compatible with Spitfire.
Your driver may not support all of the operations Spitfire provides to applications, in this case you can always throw an IOXException, or even a more specific one to let users know that the operation is unsupported.
Please note that missing features in your driver may potentially damage or alter the applications relying on them. For example, not implementing the expires method on your driver is unlikely to result in a broken application, on the other hand, not implementing write may result in your application not working at all.
Tags
Table of Contents
- __construct() : mixed
- NOTE: The driver is not made aware of the scheme it's providing. It will only serve the data. If your driver needs access to the scheme, it's likely that it's not working the right way
- atime() : mixed
- Returns the las access time of the blob. Please note that this may be affected by third party applications scanning your server's directories.
- contains() : mixed
- Returns whether the collection contains an unexpired entry for the key provided.
- delete() : mixed
- Removes the blob from the server. Drivers are allowed to perform advisory deletions, meaning that the data is not removed from the media it resides on immediately but marked as deleted instead.
- length() : mixed
- Returns the length in bytes of the blob. This is useful when performing seek operations, checking whether a drive that we wish to write to has enough capacity to receive this bob or checking whether the blob satisfies certain conditions to be transmitted over the network.
- mime() : mixed
- Returns the mime content-type for the file provided. The system may use different mechanisms for detecting the content/type or may be returning an improper one.
- mtime() : mixed
- Returns the unix timestamp the blob was modified at.
- read() : mixed
- Reads the entire blob from the source device / service / network. This is a very convenient method for handling smaller blobs like text files or memcached keys.
- readonly() : mixed
- Allows the driver to indicate that a certain key is read only and therefore not writable.
- stream() : IOStream
- Allows the application to start streaming to the storage engine. This greatly increases the responsiveness of the application since it will receive control back in regular intervals.
- url() : mixed
- Returns a public URL for the file. This allows users to download the file from a different server (eventually for a restricted amount of time)
- write() : mixed
- Writes a blob to the collection. Please note that this method requires a Blob as it's second parameter, you can easily create a blob using the blob() function with a mime type and a string.
Methods
__construct()
NOTE: The driver is not made aware of the scheme it's providing. It will only serve the data. If your driver needs access to the scheme, it's likely that it's not working the right way
public
__construct(string $dsn) : mixed
Parameters
- $dsn : string
-
Configuration string for the driver
Return values
mixed —atime()
Returns the las access time of the blob. Please note that this may be affected by third party applications scanning your server's directories.
public
atime(type $key) : mixed
Parameters
- $key : type
Return values
mixed —contains()
Returns whether the collection contains an unexpired entry for the key provided.
public
contains(string $key) : mixed
Parameters
- $key : string
Tags
Return values
mixed —delete()
Removes the blob from the server. Drivers are allowed to perform advisory deletions, meaning that the data is not removed from the media it resides on immediately but marked as deleted instead.
public
delete(type $key) : mixed
Parameters
- $key : type
Return values
mixed —length()
Returns the length in bytes of the blob. This is useful when performing seek operations, checking whether a drive that we wish to write to has enough capacity to receive this bob or checking whether the blob satisfies certain conditions to be transmitted over the network.
public
length(string $key) : mixed
While in my original vision, the length was connected to whether the system could stream the blob, it seems that certain mechanisms that do not support streaming should be able to report the size of the blob they hold.
Parameters
- $key : string
Tags
Return values
mixed —mime()
Returns the mime content-type for the file provided. The system may use different mechanisms for detecting the content/type or may be returning an improper one.
public
mime(string $key) : mixed
Do not use this to replace validating the contents of a file. A file reported as, for example, jpeg by the storage driver may actually be a PDF to a client's computer.
Parameters
- $key : string
Return values
mixed —mtime()
Returns the unix timestamp the blob was modified at.
public
mtime(string $key) : mixed
Parameters
- $key : string
Return values
mixed —read()
Reads the entire blob from the source device / service / network. This is a very convenient method for handling smaller blobs like text files or memcached keys.
public
read(string $key) : mixed
This is likely to have your server run out of memory if you're managing big files, for that you should refer to the stream() method.
This method must be implemented in a synchronous manner. It does not support asynchronous calls.
Parameters
- $key : string
Tags
Return values
mixed —readonly()
Allows the driver to indicate that a certain key is read only and therefore not writable.
public
readonly(string $key) : mixed
Parameters
- $key : string
Return values
mixed —stream()
Allows the application to start streaming to the storage engine. This greatly increases the responsiveness of the application since it will receive control back in regular intervals.
public
stream(string $key) : IOStream
This can ensure that a long file transfer does not prevent the system from attending other tasks, and the application can still inform the user about progress.
Parameters
- $key : string
Return values
IOStream —url()
Returns a public URL for the file. This allows users to download the file from a different server (eventually for a restricted amount of time)
public
url(string $key, int $ttl) : mixed
This is extremely helpful in scenarios where the storage is not on the websever but on something like Cloudy, S3 or Digital Ocean. You can just have the server generate a link that the user can use to download the file.
The link may be generated for a single use, or just as many as the user wishes. Your server does not need to host the file.
Parameters
- $key : string
- $ttl : int
Return values
mixed —write()
Writes a blob to the collection. Please note that this method requires a Blob as it's second parameter, you can easily create a blob using the blob() function with a mime type and a string.
public
write(string $key, Blob $contents[, int $ttl = null ]) : mixed
Parameters
- $key : string
- $contents : Blob
- $ttl : int = null
-
Time in seconds until the key expires and the blob should be freed