Object-Oriented API for PHP streams

Francois Zaninotto

Last update: Dec 21, 2022

Related tags

Miscellaneous Streamer

Overview

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

{
    "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:

Comments

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.

opened by peter279k 1

Question regarding stream usage

Hi,

I have a question regarding the stream. Basically I was playing with the streams to find a fix for https://github.com/auraphp/Aura.Http/issues/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.

opened by harikt 0

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

opened by absszero 0
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.
opened by k00ni 3
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?
opened by inf3rno 1

Owner

Francois Zaninotto

Open-source software enthusiast, React.js, Node.js and PHP expert, Lean & Agile management practicioner, Leadership & motivation experimenter, CEO @marmelab

GitHub