fzaninotto / streamer

Object-Oriented API for PHP streams

Streamer

Streamer is an Object-Oriented API for PHP streams.

Why should I use Streams?

A stream is a flow of bytes from one container to the other. You already use streams a lot in PHP, for instance each time you load a file into memory (file_get_contents()). You should explicitly use streams each time that:

• You need to access data from a container, but you don't know the size of this container (e.g. reading from STDIN, or a web service using streaming)
• You need to start processing data from a container before the whole transfer is finished (e.g. start zipping a file before it's all in memory)
• You need to save time and memory

What is Streamer?

PHP has a very elaborate stream API ; unfortunately, it uses functions for most stream operations (except for wrappers - go figure). Streamer is a generic library focusing on offering an object-oriented API to streams, and only that.

Installation

Streamer is published on packagist.org, so you can add it to your composer.json file for an easy installation:

composer require fzaninotto/Streamer

or

{
    "require": {
        "fzaninotto/Streamer": "0.0.1"
    }
}

Example

<?php
use Streamer\Stream,
	Streamer\FileStream,
	Streamer\NetworkStream;

// basic usage
$stream = new Stream(fopen('smiley.png', 'r'));
$image = '';
while (!$stream->isEOF()) {
  $image .= $stream->read();
}

// pipe dreams!
$stream1 = new Stream(fopen('smiley.png', 'r'));
$stream2 = new Stream(fopen('tmp.png', 'w'));
// copy the contents from the first stream to the second one
$stream1->pipe($stream2);

// factory
$fileStream = FileStream::create('smiley.png', 'r');
print_r($fileStream);

$networkStream = NetworkStream::create('tcp://www.google.com:80');
print_r($networkStream);

Credits

Streamer is heavily inspired by other Stream class implementations:

• Guzzle
• Joomla's Filesystem Stream
• Node.Js Stream API

streamer's Issues

Auto-closing the stream in __destruct() leads to invalid resource, if Stream used inside a function

I'd experienced that if you using the Stream class inside a function the __destruct function will close the stream, after the function is finished, so the according file resource is not valid anymore.

Here is a small exploit:

function streamerTest($outputStream)
{
    $stream = new \Streamer\Stream($outputStream);
    $stream->write('foo' . PHP_EOL);
}

$outputStream = tmpfile();

var_dump($outputStream);
var_dump(is_resource($outputStream));

streamerTest($outputStream);

echo "\n
after function call
\n";

var_dump($outputStream);
var_dump(is_resource($outputStream));

The output is:

resource(93) of type (stream)
bool(true)

after function call

resource(93) of type (Unknown)
bool(false)

I guess that behavior is intentional and in general maybe not wrong at all. But in case, i want to reuse the resource i given to the Stream, that behavior messing with my code.

My preference would that you make it optional and you can deactivate that behavior in the class constructor via an option or something. I can help you with that, if you want.

Stream close on object destruction not tested

Stream close on object destruction is not tested but I think it could be using unset to trigger __destruct.

This came up in #5 as well.

Project status

As title, does @fzaninotto still consider/maintain this?

It seems that this package has been inactive for the long time.

And some issues should be concerned.

FileStream::create , $context cannot be null

// factory
$fileStream = FileStream::create('smiley.png', 'r');
print_r($fileStream);
// exception: fopen() expects parameter 4 to be resource, null given` ,
// my php versoin: 5.6.17

Question regarding stream usage

Hi,

I have a question regarding the stream. Basically I was playing with the streams to find a fix for auraphp/Aura.Http#29 .

This is the code I tried.

<?php
require __DIR__ . '/vendor/autoload.php';

$networkStream = Streamer\NetworkStream::create('https://api.github.com/orgs/auraphp/repos');
print_r($networkStream);

and running it got into exception.

$ php test.php

PHP Warning:  stream_socket_client() expects parameter 6 to be resource, null given in /var/www/github.com/harikt/streamer/vendor/fzaninotto/streamer/Streamer/NetworkStream.php on line 9
PHP Fatal error:  Uncaught exception 'Streamer\Exception\InvalidArgumentException' with message 'A Stream object requires a stream resource as constructor argument' in /var/www/github.com/harikt/streamer/vendor/fzaninotto/streamer/Streamer/Stream.php:25
Stack trace:
#0 /var/www/github.com/harikt/streamer/vendor/fzaninotto/streamer/Streamer/NetworkStream.php(9): Streamer\Stream->__construct(false)
#1 /var/www/github.com/harikt/streamer/test.php(4): Streamer\NetworkStream::create('https://api.git...')
#2 {main}
  thrown in /var/www/github.com/harikt/streamer/vendor/fzaninotto/streamer/Streamer/Stream.php on line 25

Any help to understand / fix this is appreciated.

Be more oo - in the documentation

I don't think this kind of approach is oo:

new Stream(fopen('smiley.png', 'r'));

it would be better this way:

new FileStream('smiley.png');

I see now, that you have FileStream class. Why don't you use it in the documentation?