Incremental JSON encoder writing to a react/stream
To install via Composer, use the command below, it will automatically detect the latest version and bind it with
composer require wyrihaximus/react-stream-json
JsonStream implements the
react/stream and behaves like the
ThroughStream, the moment you
write* to it, it will emit data.
The following example has a fixed number of items in the JSON and can be written to
end with out needed a
$stream = new ThroughStream(); $anotherStream = new ThroughStream(); $jsonStream = new JsonStream(); $jsonStream->end([ 'key' => 'value', 'promise' => resolve('value'), 'stream' => $stream, 'nested' => [ 'a' => 'b', 'c' => 'd', ], 'nested_promises' => [ resolve('first'), resolve('second'), ], 'nested_mixed' => [ 'first', resolve($anotherStream), resolve('third'), ], ]); $stream->end('stream contents'); $anotherStream->end('second');
Stream contents will be:
All the following methods try to resolve
$value, when it encounters a promise it will wait for the promise
to resolve, and when it encounters a stream it will forward the stream's contents to it's own listeners.
Promises can resolve to a stream but not vise versa. Any other parameters will be run though
except for arrays, those will be searched through for promises and streams.
write(string $key, $value) accepts a key and a value as argument. Writing a new key and value pair to the stream.
write($value) accepts only a value as argument. Writing the value pair to the stream.
writeArray(array $values) will iterate over the items in the array and call
writeValue depending on
the type of the key.
writeObservable(ObservableInterface $values) will subscribe to the observable and call
writeValue on each item
end(array $values = ) will call
$values contains something and then or otherwise
end the stream. At that point no new values are accepted and it continues to operate any outstanding promises or streams
have been resolve/completed.
The stream doesn't know if you want to write an object or an array so it assumes an object.
It does try to detect when you haven't written anything yet and call
with an array of items. You can force writing an array or object by calling
JsonStream::createObject when creating an instance of
JsonStream. Writing object items
to a stream set up as array or vise versa will result in malformed
JSON. In short you MUST
know what kind of
JSON you will be writing.
write the key parameter isn't checked duplicates resulting in writing it
out again to the stream. Bear in mind that while
PHP considers this perfectly valid
JSON spec doesn't specify a behavior for this. So your
milage might vary, as described in section 4 of
PHP's case it will only use the value from the last occurrence.
This package ships with a factory containing factory methods for arrays
JsonStreamFactory::createFromObservable. Both will create a few stream, pause it, write the
array/observable to it, and end it.
Please see CONTRIBUTING for details.
Copyright 2019 Cees-Jan Kiewiet
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.