NOTE: For Version 3 of the AWS SDK for PHP, please see the V3 User Guide and V3 API Reference.

# 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

Namespace: Aws\S3
Located at Aws/S3/StreamWrapper.php

## 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

# `public static`
`register( `Aws\S3\S3Client` $client )`

Register the 's3://' stream wrapper

#### Parameters

$client
  ``Aws\S3\S3Client``
  $client Client to use with the stream wrapper

# `public`
`stream_close( )`

Close the stream

# `public boolean`
`stream_open( string $path, string $mode, integer $options, string & $opened_path )`

#### Parameters

$path
  `string`
  $path
$mode
  `string`
  $mode
$options
  `integer`
  $options
$opened_path
  `string`
  $opened_path

#### Returns

`boolean`
# `public boolean`
`stream_eof( )`

#### Returns

`boolean`
# `public boolean`
`stream_flush( )`

#### Returns

`boolean`
# `public string`
`stream_read( integer $count )`

Read data from the underlying stream

#### Parameters

$count
  `integer`
  $count Amount of bytes to read

#### Returns

`string`
# `public boolean`
`stream_seek( integer $offset, integer $whence = SEEK_SET )`

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`
# `public integer`
`stream_tell( )`

Get the current position of the stream

#### Returns

`integer`
Returns the current position in the stream
# `public integer`
`stream_write( string $data )`

Write data the to the stream

#### Parameters

$data
  `string`
  $data

#### Returns

`integer`
Returns the number of bytes written to the stream
# `public boolean`
`unlink( string $path )`

Delete a specific object

#### Parameters

$path
  `string`
  $path

#### Returns

`boolean`
# `public array`
`stream_stat( )`

#### Returns

`array`
# `public array`
`url_stat( string $path, integer $flags )`

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

http://www.php.net/manual/en/streamwrapper.url-stat.php
# `public boolean`
`mkdir( string $path, integer $mode, integer $options )`

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

http://www.php.net/manual/en/streamwrapper.mkdir.php
# `public boolean`
`rmdir( string $path, integer $options )`

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

http://www.php.net/manual/en/streamwrapper.rmdir.php
# `public boolean`
`dir_opendir( string $path, string $options )`

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

http://www.php.net/manual/en/function.opendir.php
# `public boolean`
`dir_closedir( )`

Close the directory listing handles

#### Returns

`boolean`
true on success
# `public boolean`
`dir_rewinddir( )`

This method is called in response to rewinddir()

#### Returns

`boolean`
true on success
# `public string`
`dir_readdir( )`

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

http://www.php.net/manual/en/function.readdir.php
# `public boolean`
`rename( string $path_from, string $path_to )`

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

http://www.php.net/manual/en/function.rename.php
# `public resource`
`stream_cast( integer $cast_as )`

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`
# `protected array`
`getOptions( )`

Get the stream context options available to the current stream

#### Returns

`array`
# `protected mixed|null`
`getOption( string $name )`

Get a specific stream context option

#### Parameters

$name
  `string`
  $name Name of the option to retrieve

#### Returns

`mixed|null`
# `protected array`
`getParams( string $path )`

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
# `protected RequestInterface`
`getSignedRequest( `Guzzle\Service\Command\CommandInterface` $command )`

Serialize and sign a command, returning a request object

#### Parameters

$command
  ``Guzzle\Service\Command\CommandInterface``
  $command Command to sign

#### Returns

`RequestInterface`
# `protected boolean`
`openReadStream( array $params, array & $errors )`

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`
# `protected boolean`
`openWriteStream( array $params, array & $errors )`

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`
# `protected boolean`
`openAppendStream( array $params, array & $errors )`

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`
# `protected boolean`
`triggerError( string|array $errors, mixed $flags = null )`

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

``Aws\Common\Exception\RuntimeException``
if throw_errors is true
# `protected array`
`formatUrlStat( string|array $result = null )`

Prepare a url_stat result array

#### Parameters

$result
  `string|array`
  $result Data to add

#### Returns

`array`
Returns the modified url_stat result
# `protected`
`clearStatInfo( string $path = null )`

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 `Aws\S3\S3Client`` | $client | # Client used to send requests
`protected string` | $mode | # Mode the stream was opened with
`protected `Guzzle\Http\EntityBody`` | $body | # Underlying stream resource
`protected array` | $params | # Current parameters to use with the flush operation
`protected `Aws\S3\Iterator\ListObjectsIterator`` | $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.