austinhyde/paperboat

A streaming JSON emitter

v0.1.0 2015-05-04 03:56 UTC

Requires

• php: >=5.4.0

Requires (Dev)

• phpunit/phpunit: 4.*

MIT

• Austin Hyde

README

This is an extremely simple, and very alpha quality implementation of a Streaming JSON outputter.

Show me the goods

$stream = new PaperBoat\JsonStream();
$stream
  ->startObject()
  ->property('data')
  ->startArray();

$i = 0;
while ($row = $pdoStmt->fetch(PDO::FETCH_ASSOC)) {
  $i++;
  $stream->value($row);
}

$stream
  ->stopArray()
  ->property('meta')
  ->startObject()
    ->property('count', $i)
  ->stopObject()
  ->stopObject();  

This outputs, for example,

{"data":[{"id":1,"name":"Bill Murray"},{"id":2,"name":"Tom Hanks"},{"id":3,"name":"Sigourney Weaver"}],"meta":{"count":3}}

Usage

The primary class you interact with is PaperBoat\JsonStream. The constructor takes an optional PaperBoat\OutputStream parameter, which tells it where to output JSON to. By default, this is a PaperBoat\OutputStream\StdoutStream, which just prints to STDOUT or the HTTP response.

The following methods construct JSON output:

• startArray() - Begins outputting an array.
• stopArray() - Closes an array.
• startObject() - Begins outputting an object.
• stopObject() - Closes an object.
• property($name[, $data]) - Adds a property to an object. If you do not provide the value here, you must call startArray(), startObject(), or value() next.
• value($data) - Adds data to the stream, by JSON encoding it.

The following methods control how data is output:

• setAutomaticFlushing($value) - Controls whether the OutputStream is flushed automatically after data is written to the stream. Defaults to true. If you set this false, you are responsible for calling ->flush() when appropriate.
• setJsonFlags($value) - Sets the flags passed to json_encode()
• flush() - Simply calls the provided OutputStream's flush() method.

Installation

Via Composer.

$ composer require austinhyde/paperboat

Contributing

See CONTRIBUTING

FAQ

Why PaperBoat?

Streams of lightweight data => paper boats floating down a stream of water

Why do I need this?

You would use this if you need to output a large amount of JSON data without holding the whole data structure in memory at once.

Most people probably don't need this.

Why did you make this?

1. I was bored
2. It didn't exist yet
3. Someone might need it, someday

Are these really frequently asked questions?

No, this is a sham, just like all the other FAQs on GitHub.