Class StreamWrapper
Amazon S3 stream wrapper to use "s3://<bucket>/<key>" files with PHP streams, supporting "r", "w", "a", "x".
# Supported stream related PHP functions:
- fopen, fclose, fread, fwrite, fseek, ftell, feof, fflush
- opendir, closedir, readdir, rewinddir
- copy, rename, unlink
- mkdir, rmdir, rmdir (recursive)
- file_get_contents, file_put_contents
- file_exists, filesize, is_file, is_dir
# 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
Methods summary
-
public static
register ( Aws\S3\S3Client $client )
Register the 's3://' stream wrapper
-
public
stream_close ( )
Close the stream
-
public
stream_open ( string $path, string $mode, int $options, string & $opened_path )
-
public
stream_eof ( )
-
public
stream_flush ( )
-
public
stream_read ( int $count )
Read data from the underlying stream
-
public
stream_seek ( int $offset, int $whence = SEEK_SET )
Seek to a specific byte in the stream
-
public
stream_tell ( )
Get the current position of the stream
-
public
stream_write ( string $data )
Write data the to the stream
-
public
unlink ( string $path )
Delete a specific object
-
public
stream_stat ( )
-
public
url_stat ( string $path, int $flags )
Provides information for is_dir, is_file, filesize, etc. Works on buckets, keys, and prefixes
-
public
mkdir ( string $path, int $mode, int $options )
Support for mkdir().
-
public
rmdir ( string $path, int $options )
Remove a bucket from Amazon S3
-
public
dir_opendir ( string $path, string $options )
Support for opendir().
-
public
dir_closedir ( )
Close the directory listing handles
-
public
dir_rewinddir ( )
This method is called in response to rewinddir()
-
public
dir_readdir ( )
This method is called in response to readdir()
-
public
rename ( string $path_from, string $path_to )
Called in response to rename() to rename a file or directory. Currently only supports renaming objects.
-
public
stream_cast ( int $cast_as )
Cast the stream to return the underlying file resource
-
protected
getOptions ( )
Get the stream context options available to the current stream
-
protected
getOption ( string $name )
Get a specific stream context option
-
protected
getParams ( string $path )
Get the bucket and key from the passed path (e.g. s3://bucket/key)
-
protected
getSignedRequest ( CommandInterface $command )
Serialize and sign a command, returning a request object
-
protected
openReadStream ( array $params, array & $errors )
Initialize the stream wrapper for a read only stream
-
protected
openWriteStream ( array $params, array & $errors )
Initialize the stream wrapper for a write only stream
-
protected
openAppendStream ( array $params, array & $errors )
Initialize the stream wrapper for an append stream
-
protected
triggerError ( string|array $errors, mixed $flags = null )
Trigger one or more errors
-
protected
formatUrlStat ( string|array $result = null )
Prepare a url_stat result array
-
protected
clearStatInfo ( string $path = null )
Clear the next stat result from the cache
Methods detail
Register the 's3://' stream wrapper
Parameters
- $client
Aws\S3\S3Client
$client Client to use with the stream wrapper
Close the stream
Parameters
- $path
string
$path- $mode
string
$mode- $options
integer
$options- $opened_path
string
$opened_path
Returns
boolean
Returns
boolean
Returns
boolean
Read data from the underlying stream
Parameters
- $count
integer
$count Amount of bytes to read
Returns
string
Seek to a specific byte in the stream
Parameters
- $offset
integer
$offset Seek offset- $whence
integer
$whence Whence (SEEK_SET, SEEK_CUR, SEEK_END)
Returns
boolean
Get the current position of the stream
Returns
integer
Returns the current position in the stream
Write data the to the stream
Parameters
- $data
string
$data
Returns
integer
Returns the number of bytes written to the stream
Delete a specific object
Parameters
- $path
string
$path
Returns
boolean
Returns
array
Provides information for is_dir, is_file, filesize, etc. Works on buckets, keys, and prefixes
Parameters
- $path
string
$path- $flags
integer
$flags
Returns
array
Returns an array of stat data
Link
Support for mkdir().
Parameters
- $path
string
$path Directory which should be created.- $mode
integer
$mode 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
integer
$options A bitwise mask of values, such as STREAM_MKDIR_RECURSIVE.
Returns
boolean
Link
Remove a bucket from Amazon S3
Parameters
- $path
string
$path the directory path- $options
integer
$options A bitwise mask of values
Returns
boolean
true if directory was successfully removed
Link
Support for opendir().
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
$path The path to the directory (e.g. "s3://dir[</prefix>]")- $options
string
$options Whether or not to enforce safe_mode (0x04). Unused.
Returns
boolean
true on success
See
Close the directory listing handles
Returns
boolean
true on success
This method is called in response to rewinddir()
Returns
boolean
true on success
This method is called in response to readdir()
Returns
string
Should return a string representing the next filename, or false if there is no next file.
Link
Called in response to rename() to rename a file or directory. Currently only supports renaming objects.
Parameters
- $path_from
string
$path_from the path to the file to rename- $path_to
string
$path_to the new path to the file
Returns
boolean
true if file was successfully renamed
Link
Cast the stream to return the underlying file resource
Parameters
- $cast_as
integer
$cast_as STREAM_CAST_FOR_SELECT or STREAM_CAST_AS_STREAM
Returns
resource
Get the stream context options available to the current stream
Returns
array
Get a specific stream context option
Parameters
- $name
string
$name Name of the option to retrieve
Returns
mixed|null
Get the bucket and key from the passed path (e.g. s3://bucket/key)
Parameters
- $path
string
$path Path passed to the stream wrapper
Returns
array
Hash of 'Bucket', 'Key', and custom params
Serialize and sign a command, returning a request object
Parameters
- $command
Guzzle\Service\Command\CommandInterface
$command Command to sign
Returns
RequestInterface
Initialize the stream wrapper for a read only stream
Parameters
- $params
array
$params Operation parameters- $errors
array
$errors Any encountered errors to append to
Returns
boolean
Initialize the stream wrapper for a write only stream
Parameters
- $params
array
$params Operation parameters- $errors
array
$errors Any encountered errors to append to
Returns
boolean
Initialize the stream wrapper for an append stream
Parameters
- $params
array
$params Operation parameters- $errors
array
$errors Any encountered errors to append to
Returns
boolean
Trigger one or more errors
Parameters
- $errors
string|array
$errors Errors to trigger- $flags
mixed
$flags If set to STREAM_URL_STAT_QUIET, then no error or exception occurs
Returns
boolean
Returns false
Throws
Prepare a url_stat result array
Parameters
- $result
string|array
$result Data to add
Returns
array
Returns the modified url_stat result
Clear the next stat result from the cache
Parameters
- $path
string
$path If a path is specific, clearstatcache() will be called
Magic methods summary
Properties summary
public
resource|null
|
$context |
#
Stream context (this is set by PHP when a context is used) |
protected static
|
$client |
#
Client used to send requests |
protected
string
|
$mode |
#
Mode the stream was opened with |
protected
|
$body |
#
Underlying stream resource |
protected
array
|
$params |
#
Current parameters to use with the flush operation |
protected
|
$objectIterator |
#
Iterator used with opendir() and subsequent readdir() calls |
protected
string
|
$openedBucket |
#
The bucket that was opened when opendir() was called |
protected
string
|
$openedBucketPrefix |
#
The prefix of the bucket that was opened with opendir() |
protected static
array
|
$nextStat |
#
The next key to retrieve when using a directory iterator. Helps for fast directory traversal. |