README

A safe OOP wrapper around resource streams in PHP:

• No need to worry about streams that have been closed.
• Instead of returning false, detailed exceptions are thrown when something goes wrong.
• Streams are automatically closed when the object is destructed (with option to opt-out).
• Handy factory methods for common streams.

Installation

composer require phpro/resource-stream

Usage

use Phpro\ResourceStream\ResourceStream;

$stream = (new ResourceStream(fopen('php://temp', 'r+')))
    ->write('Hello World')
    ->rewind();

// Various ways to read:
echo $stream->read();
echo $stream->read($bufferSize);
echo $stream->readLine();
echo $stream->readLine($bufferSize, ending: \PHP_EOL);
echo $stream->getContents();

// Or in batches (Generator<string>)
$cursor = $stream->readBatches($bufferSize);
$cursor = $stream->readLines($bufferSize, ending: \PHP_EOL); 

// Get access to PHP's inner resource stream
$innerStream = $stream->unwrap();

// Get access to common information:
$stream->isOpen();
$stream->isEof();
$stream->uri();
$stream->size();

// Possibility to copy contents across streams
$stream->copyTo($anotherStream);
$stream->copyFrom($anotherStream);

// Streams will automatically be closed on destruction.
// Of course, you can choose to keep it open or close it manually:
$stream->keepAlive();
$stream->close();

Built-in Streams

The following streams are available by default:

CliStream

Can be used to open up CLI stdin, stdout and stderr streams.

use Phpro\ResourceStream\Factory\CliStream;

$stdin = CliStream::stdin();
$stdout = CliStream::stdout();
$stderr = CliStream::stderr();

FileStream

Validates if the local file exists and opens it up for you to use.

use Phpro\ResourceStream\Factory\FileStream;

$stream = FileStream::create('/path/to/file', FileStream::READ_WRITE_MODE);

IOStream

Can be used to open up CGI php://input and php://output streams.

use Phpro\ResourceStream\Factory\IOStream;

$input = IOStream::input();
$output = IOStream::output();

MemoryStream

Creates an in-memory stream for you to use.

use Phpro\ResourceStream\Factory\MemoryStream;

$stream = MemoryStream::create();

Psr7Stream

Creates a stream from a PSR-7 stream / request / response. before you can use this stream, you'll need to install the guzzlehttp/psr-7 package which contains a stream wrapper implementation.

composer require psr/http-message guzzlehttp/psr-7

use Phpro\ResourceStream\Factory\Psr7Stream;

$stream = Psr7Stream::createFromStream($anyPsr7Stream);
$stream = Psr7Stream::createFromRequest($anyPsr7Request);
$stream = Psr7Stream::createFromResponse($anyPsr7Response);

TmpStream

Creates a temporary file and opens it up for you to use. After the stream is closed, the temporary file will be removed.

use Phpro\ResourceStream\Factory\TmpStream;

$stream = TmpStream::create();

ZipStream

Opens a single entry from a zip archive as a read-only stream. Validates that the archive exists before opening; failures (missing entry, corrupt archive, wrong/missing password) surface as a StreamActionFailureException carrying the underlying PHP message.

use Phpro\ResourceStream\Factory\ZipStream;

$stream = ZipStream::read('/path/to/archive.zip', 'folder/file.txt');

// For encrypted entries, pass any options accepted by the `zip` stream context:
$stream = ZipStream::read('/path/to/archive.zip', 'secret.txt', ['password' => 'secret']);

Note: the zip:// stream wrapper is read-only. To write into an archive, use PHP's ZipArchive directly.