README

Reference implementations of stream-interop/interface.

Installation

Install this package via Composer:

$ composer require stream-interop/impl

Implementations

File Streams

ConsumableFileStream

A unidirectional readable stream; does not afford seeking or writing.

$stream = new \StreamInterop\Impl\ConsumableFileStream(fopen('/path/to/file', 'rb'));

$stream->read(2);       // reads the first 2 bytes
$stream->read(4);       // reads the next 4 bytes
$stream->getContents(); // reads all remaining bytes
$stream->eof();         // true

ReadableFileStream

A readable stream that affords seeking and stringability.

$stream = new \StreamInterop\Impl\ReadableFileStream(fopen('/path/to/file', 'rb'));

$stream->read(2);       // reads the first 2 bytes
$stream->read(4);       // reads the next 4 bytes
$stream->getContents(); // reads all remaining bytes
$stream->eof();         // true
$stream->__toString();  // rewinds and reads the entire file

$stream->rewind();      // rewinds the pointer
$stream->seek(7);       // moves to byte 7
$stream->read(3);       // reads the next 3 bytes

ReadonlyFileStream

Identical to the ReadableFileStream, but it makes a copy of the original resource to enforce readonly constraints. If the original resource is modified, the ReadonlyFileStream will not reflect those changes.

// create the origin file
$file = '/path/to/file';
file_put_contents($file, 'foo bar');

// initialize a readonly stream from the file;
// the readonly stream reads the file into memory.
$stream = new \StreamInterop\Impl\ReadonlyFileStream($file);
assert((string) $stream === file_get_contents($file));

// change the origin file
file_put_contents($file, 'baz dib');

// the stream does not reflect the changes
assert((string) $stream !== file_get_contents($file));

ReadWriteFileStream

A fully read+write stream that affords seeking, appending, and stringability.

$stream = new \StreamInterop\Impl\ReadWriteFileStream(fopen('/path/to/file', 'wb+'));

$stream->write('Hello ');
$stream->rewind();
$stream->append('World!');
$stream->rewind();
$stream->read(2);           // reads "He"
$stream->read(4);           // reads "llo "
$stream->getContents();     // reads "World!"
$stream->eof();             // true
$stream->__toString();      // reads "Hello World!"

WritableFileStream

A unidirectional writable stream; does not afford seeking or reading.

$stream = new \StreamInterop\Impl\WritableFileStream(fopen('/path/to/file', 'wb'));

$stream->write('Hello World!');

Lazy Ghost File Objects

These streams open a resource themselves on a specified filename.

ReadableFile

A readable lazy-opening stream that affords seeking and stringability.

// construct with a file name, not an open resource
$stream = new \StreamInterop\Impl\ReadableFile('/path/to/file');

$stream->read(2);           // reads the first 2 bytes
$stream->read(4);           // reads the next 4 bytes
$stream->getContents();     // reads all remaining bytes
$stream->eof();             // true
$stream->__toString();      // rewinds and reads the entire file

$stream->rewind();          // rewinds the pointer
$stream->seek(7);           // moves to byte 7
$stream->read(3);           // reads the next 3 bytes

ReadWriteFile

A fully read+write lazy-opening stream that affords seeking and stringability.

// construct with a file name, not an open resource
$stream = new \StreamInterop\Impl\ReadWriteFile('/path/to/file');

$stream->write('Hello World!');
$stream->rewind();
$stream->read(2);           // reads "He"
$stream->read(4);           // reads "llo "
$stream->getContents();     // reads "World!"
$stream->eof();             // true
$stream->__toString();      // reads "Hello World!"

Non-Resource Streams

StringStream

A fully read+write stream that affords seeking and stringability, backed by a string instead of a resource.

// construct with string data, not a resource of file name
$stream = new \StreamInterop\Impl\StringStream('Hello');

$stream->read(2);           // reads 'He'
$stream->getContents();     // reads 'llo'
$stream->write(' World!');

$stream->rewind();
$stream->getContents();     // reads 'Hello World!'