Documentation

StreamWrapper
in package

Amazon S3 stream wrapper to use "s3://<bucket>/<key>" files with PHP streams, supporting "r", "w", "a", "x".

Opening "r" (read only) streams:

Read only streams are truly streaming by default and will not allow you to seek. This is because data read from the stream is not kept in memory or on the local filesystem. You can force a "r" stream to be seekable by setting the "seekable" stream context option true. This will allow true streaming of data from Amazon S3, but will maintain a buffer of previously read bytes in a 'php://temp' stream to allow seeking to previously read bytes from the stream.

You may pass any GetObject parameters as 's3' stream context options. These options will affect how the data is downloaded from Amazon S3.

Opening "w" and "x" (write only) streams:

Because Amazon S3 requires a Content-Length header, write only streams will maintain a 'php://temp' stream to buffer data written to the stream until the stream is flushed (usually by closing the stream with fclose).

You may pass any PutObject parameters as 's3' stream context options. These options will affect how the data is uploaded to Amazon S3.

When opening an "x" stream, the file must exist on Amazon S3 for the stream to open successfully.

Opening "a" (write only append) streams:

Similar to "w" streams, opening append streams requires that the data be buffered in a "php://temp" stream. Append streams will attempt to download the contents of an object in Amazon S3, seek to the end of the object, then allow you to append to the contents of the object. The data will then be uploaded using a PutObject operation when the stream is flushed (usually with fclose).

You may pass any GetObject and/or PutObject parameters as 's3' stream context options. These options will affect how the data is downloaded and uploaded from Amazon S3.

Stream context options:

  • "seekable": Set to true to create a seekable "r" (read only) stream by using a php://temp stream buffer
  • For "unlink" only: Any option that can be passed to the DeleteObject operation

Table of Contents

$context  : resource|null
$body  : StreamInterface
$cache  : CacheInterface
$isFlushed  : bool
$mode  : string
$objectIterator  : Iterator
$openedBucket  : string
$openedBucketPrefix  : string
$openedPath  : string
$params  : array<string|int, mixed>
$protocol  : string
$size  : int
dir_closedir()  : bool
Close the directory listing handles
dir_opendir()  : bool
Support for opendir().
dir_readdir()  : string
This method is called in response to readdir()
dir_rewinddir()  : bool
This method is called in response to rewinddir()
mkdir()  : bool
Support for mkdir().
register()  : mixed
Register the 's3://' stream wrapper
rename()  : bool
Called in response to rename() to rename a file or directory. Currently only supports renaming objects.
rmdir()  : mixed
stream_cast()  : mixed
stream_close()  : mixed
stream_eof()  : mixed
stream_flush()  : mixed
stream_open()  : mixed
stream_read()  : mixed
stream_seek()  : mixed
stream_stat()  : mixed
stream_tell()  : mixed
stream_write()  : mixed
unlink()  : mixed
url_stat()  : mixed
Provides information for is_dir, is_file, filesize, etc. Works on buckets, keys, and prefixes.
boolCall()  : bool
Invokes a callable and triggers an error if an exception occurs while calling the function.
clearCacheKey()  : mixed
Clears a specific stat cache value from the stat cache and LRU cache.
createBucket()  : bool
Creates a bucket for the given parameters.
createStat()  : mixed
createSubfolder()  : bool
Creates a pseudo-folder by creating an empty "/" suffixed key
deleteSubfolder()  : bool
Deletes a nested subfolder if it is empty.
determineAcl()  : string
Determine the most appropriate ACL based on a file mode.
formatKey()  : mixed
formatUrlStat()  : array<string|int, mixed>
Prepare a url_stat result array
getBucketKey()  : mixed
getCacheStorage()  : LruArrayCache
getClient()  : S3ClientInterface
Gets the client from the stream context
getOption()  : mixed|null
Get a specific stream context option
getOptions()  : array<string|int, mixed>
Get the stream context options available to the current stream
getSize()  : int|null
Returns the size of the opened object body.
getStatTemplate()  : array<string|int, mixed>
Gets a URL stat template with default values
initProtocol()  : mixed
Parse the protocol out of the given path.
openAppendStream()  : mixed
openReadStream()  : mixed
openWriteStream()  : mixed
statDirectory()  : mixed
triggerError()  : bool
Trigger one or more errors
validate()  : mixed
Validates the provided stream arguments for fopen and returns an array of errors.
withPath()  : array<string|int, mixed>
Get the bucket and key from the passed path (e.g. s3://bucket/key)

Properties

$context

public resource|null $context

Stream context (this is set by PHP)

$isFlushed

private bool $isFlushed = false

Keeps track of whether stream has been flushed since opening

$mode

private string $mode

Mode in which the stream was opened

$objectIterator

private Iterator $objectIterator

Iterator used with opendir() related calls

$openedBucket

private string $openedBucket

The bucket that was opened when opendir() was called

$openedBucketPrefix

private string $openedBucketPrefix

The prefix of the bucket that was opened with opendir()

$params

private array<string|int, mixed> $params = []

Hash of opened stream parameters

$protocol

private string $protocol = 's3'

The opened protocol (e.g., "s3")

Methods

dir_closedir()

Close the directory listing handles

public dir_closedir() : bool
Return values
bool —

true on success

dir_opendir()

Support for opendir().

public dir_opendir(string $path, string $options) : bool

The opendir() method of the Amazon S3 stream wrapper supports a stream context option of "listFilter". listFilter must be a callable that accepts an associative array of object data and returns true if the object should be yielded when iterating the keys in a bucket.

Parameters
$path : string

The path to the directory (e.g. "s3://dir[]")

$options : string

Unused option variable

Tags
see
http://www.php.net/manual/en/function.opendir.php
Return values
bool —

true on success

dir_rewinddir()

This method is called in response to rewinddir()

public dir_rewinddir() : bool
Return values
bool —

true on success

mkdir()

Support for mkdir().

public mkdir(string $path, int $mode, int $options) : bool
Parameters
$path : string

Directory which should be created.

$mode : int

Permissions. 700-range permissions map to ACL_PUBLIC. 600-range permissions map to ACL_AUTH_READ. All other permissions map to ACL_PRIVATE. Expects octal form.

$options : int

A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.

Tags
link
http://www.php.net/manual/en/streamwrapper.mkdir.php
Return values
bool —

register()

Register the 's3://' stream wrapper

public static register(S3ClientInterface $client[, string $protocol = 's3' ][, CacheInterface $cache = null ]) : mixed
Parameters
$client : S3ClientInterface

Client to use with the stream wrapper

$protocol : string = 's3'

Protocol to register as.

$cache : CacheInterface = null

Default cache for the protocol.

Return values
mixed —

rename()

Called in response to rename() to rename a file or directory. Currently only supports renaming objects.

public rename(string $path_from, string $path_to) : bool
Parameters
$path_from : string

the path to the file to rename

$path_to : string

the new path to the file

Tags
link
http://www.php.net/manual/en/function.rename.php
Return values
bool —

true if file was successfully renamed

rmdir()

public rmdir(mixed $path, mixed $options) : mixed
Parameters
$path : mixed
$options : mixed
Return values
mixed —

stream_cast()

public stream_cast(mixed $cast_as) : mixed
Parameters
$cast_as : mixed
Return values
mixed —

stream_close()

public stream_close() : mixed
Return values
mixed —

stream_eof()

public stream_eof() : mixed
Return values
mixed —

stream_flush()

public stream_flush() : mixed
Return values
mixed —

stream_open()

public stream_open(mixed $path, mixed $mode, mixed $options, mixed &$opened_path) : mixed
Parameters
$path : mixed
$mode : mixed
$options : mixed
$opened_path : mixed
Return values
mixed —

stream_read()

public stream_read(mixed $count) : mixed
Parameters
$count : mixed
Return values
mixed —

stream_seek()

public stream_seek(mixed $offset[, mixed $whence = SEEK_SET ]) : mixed
Parameters
$offset : mixed
$whence : mixed = SEEK_SET
Return values
mixed —

stream_stat()

public stream_stat() : mixed
Return values
mixed —

stream_tell()

public stream_tell() : mixed
Return values
mixed —

stream_write()

public stream_write(mixed $data) : mixed
Parameters
$data : mixed
Return values
mixed —

unlink()

public unlink(mixed $path) : mixed
Parameters
$path : mixed
Return values
mixed —

boolCall()

Invokes a callable and triggers an error if an exception occurs while calling the function.

private boolCall(callable $fn[, int $flags = null ]) : bool
Parameters
$fn : callable
$flags : int = null
Return values
bool —

clearCacheKey()

Clears a specific stat cache value from the stat cache and LRU cache.

private clearCacheKey(string $key) : mixed
Parameters
$key : string

S3 path (s3://bucket/key).

Return values
mixed —

createBucket()

Creates a bucket for the given parameters.

private createBucket(string $path, array<string|int, mixed> $params) : bool
Parameters
$path : string

Stream wrapper path

$params : array<string|int, mixed>

A result of StreamWrapper::withPath()

Return values
bool —

Returns true on success or false on failure

createStat()

private createStat(mixed $path, mixed $flags) : mixed
Parameters
$path : mixed
$flags : mixed
Return values
mixed —

createSubfolder()

Creates a pseudo-folder by creating an empty "/" suffixed key

private createSubfolder(string $path, array<string|int, mixed> $params) : bool
Parameters
$path : string

Stream wrapper path

$params : array<string|int, mixed>

A result of StreamWrapper::withPath()

Return values
bool —

deleteSubfolder()

Deletes a nested subfolder if it is empty.

private deleteSubfolder(string $path, array<string|int, mixed> $params) : bool
Parameters
$path : string

Path that is being deleted (e.g., 's3://a/b/c')

$params : array<string|int, mixed>

A result of StreamWrapper::withPath()

Return values
bool —

determineAcl()

Determine the most appropriate ACL based on a file mode.

private determineAcl(int $mode) : string
Parameters
$mode : int

File mode

Return values
string —

formatKey()

private formatKey(mixed $key) : mixed
Parameters
$key : mixed
Return values
mixed —

formatUrlStat()

Prepare a url_stat result array

private formatUrlStat([string|array<string|int, mixed> $result = null ]) : array<string|int, mixed>
Parameters
$result : string|array<string|int, mixed> = null

Data to add

Return values
array<string|int, mixed> —

Returns the modified url_stat result

getBucketKey()

private getBucketKey(mixed $path) : mixed
Parameters
$path : mixed
Return values
mixed —

getOption()

Get a specific stream context option

private getOption(string $name) : mixed|null
Parameters
$name : string

Name of the option to retrieve

Return values
mixed|null —

getOptions()

Get the stream context options available to the current stream

private getOptions([bool $removeContextData = false ]) : array<string|int, mixed>
Parameters
$removeContextData : bool = false

Set to true to remove contextual kvp's like 'client' from the result.

Return values
array<string|int, mixed> —

getSize()

Returns the size of the opened object body.

private getSize() : int|null
Return values
int|null —

getStatTemplate()

Gets a URL stat template with default values

private getStatTemplate() : array<string|int, mixed>
Return values
array<string|int, mixed> —

initProtocol()

Parse the protocol out of the given path.

private initProtocol( $path) : mixed
Parameters
$path :
Return values
mixed —

openAppendStream()

private openAppendStream() : mixed
Return values
mixed —

openReadStream()

private openReadStream() : mixed
Return values
mixed —

openWriteStream()

private openWriteStream() : mixed
Return values
mixed —

statDirectory()

private statDirectory(mixed $parts, mixed $path, mixed $flags) : mixed
Parameters
$parts : mixed
$path : mixed
$flags : mixed
Return values
mixed —

triggerError()

Trigger one or more errors

private triggerError(string|array<string|int, mixed> $errors[, mixed $flags = null ]) : bool
Parameters
$errors : string|array<string|int, mixed>

Errors to trigger

$flags : mixed = null

If set to STREAM_URL_STAT_QUIET, then no error or exception occurs

Tags
throws
RuntimeException

if throw_errors is true

Return values
bool —

Returns false

validate()

Validates the provided stream arguments for fopen and returns an array of errors.

private validate(mixed $path, mixed $mode) : mixed
Parameters
$path : mixed
$mode : mixed
Return values
mixed —

withPath()

Get the bucket and key from the passed path (e.g. s3://bucket/key)

private withPath(string $path) : array<string|int, mixed>
Parameters
$path : string

Path passed to the stream wrapper

Return values
array<string|int, mixed> —

Hash of 'Bucket', 'Key', and custom params from the context

Search results