{"id":13828454,"url":"https://github.com/violet-php/streaming-json-encoder","last_synced_at":"2025-05-11T19:26:58.657Z","repository":{"id":13517685,"uuid":"74651109","full_name":"violet-php/streaming-json-encoder","owner":"violet-php","description":"PHP library for iteratively encoding large JSON documents piece by piece","archived":false,"fork":false,"pushed_at":"2023-10-23T06:45:41.000Z","size":115,"stargazers_count":312,"open_issues_count":4,"forks_count":16,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-05-17T07:42:48.381Z","etag":null,"topics":["encoder","json","php","php-library","psr-7","streaming"],"latest_commit_sha":null,"homepage":"http://violet.riimu.net","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/violet-php.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-24T08:03:32.000Z","updated_at":"2024-06-18T12:39:55.036Z","dependencies_parsed_at":"2024-06-18T12:39:52.678Z","dependency_job_id":"f6df5caa-42d9-4f21-a8b9-e32a306a64fb","html_url":"https://github.com/violet-php/streaming-json-encoder","commit_stats":{"total_commits":69,"total_committers":4,"mean_commits":17.25,"dds":0.04347826086956519,"last_synced_commit":"ef1b32764c1507ddc3aadf8ac3d9d9b7fa6a86fc"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/violet-php%2Fstreaming-json-encoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/violet-php%2Fstreaming-json-encoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/violet-php%2Fstreaming-json-encoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/violet-php%2Fstreaming-json-encoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/violet-php","download_url":"https://codeload.github.com/violet-php/streaming-json-encoder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253619997,"owners_count":21937287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["encoder","json","php","php-library","psr-7","streaming"],"created_at":"2024-08-04T09:02:47.591Z","updated_at":"2025-05-11T19:26:58.610Z","avatar_url":"https://github.com/violet-php.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Streaming JSON Encoder #\n\n*Streaming JSON Encoder* is a PHP library that provides a set of classes to help\nwith encoding JSON in a streaming manner, i.e. allowing you to encode the JSON\ndocument bit by bit rather than encoding the whole document at once. Compared to\nthe built in `json_encode` function, there are two main advantages:\n\n  * You will not need to load the entire data set into memory, as the encoder\n    supports iterating over both arrays and any kind of iterators, like\n    generators, for example.\n  * You will not need to load the entire resulting JSON document into the\n    memory, since the JSON document will be encoded value by value and it's\n    possible to output the encoded document piece by piece.\n    \nIn other words, the Streaming JSON Encoder can provide the greatest benefit\nwhen you need to handle large data sets that may otherwise take up too much\nmemory to process.\n\nIn order to increase interoperability, the library also provides a PSR-7\ncompatible stream to use with frameworks and HTTP requests.\n\nThe API documentation is available at: http://violet.riimu.net/api/streaming-json-encoder/\n\n[![CI](https://img.shields.io/github/workflow/status/violet-php/streaming-json-encoder/CI/main?style=flat-square)](https://github.com/violet-php/streaming-json-encoder/actions)\n[![Scrutinizer](https://img.shields.io/scrutinizer/quality/g/violet-php/streaming-json-encoder/main?style=flat-square)](https://scrutinizer-ci.com/g/violet-php/streaming-json-encoder/)\n[![codecov](https://img.shields.io/codecov/c/github/violet-php/streaming-json-encoder/main?style=flat-square)](https://codecov.io/gh/violet-php/streaming-json-encoder)\n[![Packagist](https://img.shields.io/packagist/v/violet/streaming-json-encoder.svg?style=flat-square)](https://packagist.org/packages/violet/streaming-json-encoder)\n\n## Requirements ##\n\n  * The minimum supported PHP version is 5.6\n  * The library depends on the following external PHP libraries:\n    * [psr/http-message](https://packagist.org/packages/psr/http-message) (`^1.0`)\n\n## Installation ##\n\n### Installation with Composer ###\n\nThe easiest way to install this library is to use Composer to handle your\ndependencies. In order to install this library via Composer, simply follow\nthese two steps:\n\n  1. Acquire the `composer.phar` by running the Composer\n     [Command-line installation](https://getcomposer.org/download/)\n     in your project root.\n\n  2. Once you have run the installation script, you should have the `composer.phar`\n     file in you project root and you can run the following command:\n\n     ```\n     php composer.phar require \"violet/streaming-json-encoder:^1.1\"\n     ```\n\nAfter installing this library via Composer, you can load the library by\nincluding the `vendor/autoload.php` file that was generated by Composer during\nthe installation.\n\n### Adding the library as a dependency ###\n    \nIf you are already familiar with how to use Composer, you may alternatively add\nthe library as a dependency by adding the following `composer.json` file to your\nproject and running the `composer install` command:\n\n```json\n{\n    \"require\": {\n        \"violet/streaming-json-encoder\": \"^1.1\"\n    }\n}\n```\n\n### Manual installation ###\n\nIf you do not wish to use Composer to load the library, you may also download\nthe library manually by downloading the [latest release](https://github.com/violet-php/streaming-json-encoder/releases/latest)\nand extracting the `src` folder to your project. You may then include the\nprovided `src/autoload.php` file to load the library classes.\n\nPlease note that using Composer will also automatically download the other\nrequired PHP libraries. If you install this library manually, you will also need\nto make those other required libraries available.\n\n## Usage ##\n\nThis library offers 3 main different ways to use the library via the classes\n`BufferJsonEncoder`, `StreamJsonEncoder` and the PSR-7 compatible stream\n`JsonStream`.\n\n### Using BufferJsonEncoder ###\n\nThe buffer encoder is most useful when you need to generate the JSON document\nin a way that does not involve passing callbacks to handle the generated JSON.\n\nThe easiest way to use the `BufferJsonEncoder` is to instantiate it with the\nJSON value to encode and call the `encode()` method to return the entire output\nas a string:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$encoder = new \\Violet\\StreamingJsonEncoder\\BufferJsonEncoder(['array_value']);\necho $encoder-\u003eencode();\n```\n\nThe most useful way to use this encoder, however, is to use it as an iterator.\nAs the encoder implements the `Iterator` interface, you can simply loop over the\ngenerated JSON with a foreach loop:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$encoder = new \\Violet\\StreamingJsonEncoder\\BufferJsonEncoder(range(0, 10));\n\nforeach ($encoder as $string) {\n    echo $string;\n}\n```\n\nIt's also worth noting that the encoder supports iterators for values. What's\nmore, any closure passed to the encoder will also be called and the return value\nused as the value instead. The previous example could also be written as:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$encoder = new \\Violet\\StreamingJsonEncoder\\BufferJsonEncoder(function () {\n    for ($i = 0; $i \u003c= 10; $i++) {\n        yield $i;\n    }\n});\n\nforeach ($encoder as $string) {\n    echo $string;\n}\n```\n\nAs a side note, the encoder will respect the `JsonSerializable` interface as\nwell and will call the `jsonSerialize` for objects that implement the interface.\n\n### Using StreamJsonEncoder ###\n\nThe stream encoder works very similarly to the `BufferJsonEncoder` as they\nextend the same abstract class. However, the key difference is in how they\nhandle passing the JSON output.\n\nThe `StreamJsonEncoder` accepts a callable as the second constructor argument.\nWhenever JSON needs to be outputted, this callable is called with two arguments,\nthe actual string to output and the type of the token to output (which is one\nof the `JsonToken` constants).\n\nIf no callable is passed, the StreamJsonEncoder will simply output the JSON\nusing an echo statement. For example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$encoder = new \\Violet\\StreamingJsonEncoder\\StreamJsonEncoder(['array_value']);\n$encoder-\u003eencode();\n```\n\nThe `encode()` method in `StreamJsonEncoder` returns the total number of bytes\nit passed to the output. This encoder makes it convenient, for example, to\nwrite the JSON to file in a streaming manner. For example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$fp = fopen('test.json', 'wb');\n$encoder = new \\Violet\\StreamingJsonEncoder\\StreamJsonEncoder(\n    range(1, 100),\n    function ($json) use ($fp) {\n        fwrite($fp, $json);\n    }\n);\n\n$encoder-\u003eencode();\nfclose($fp);\n```\n\n### Using JsonStream ###\n\nThe stream class provides a PSR-7 compatible `StreamInterface` for streaming\nJSON content. It actually uses the `BufferJsonEncoder` to do the hard work and\nsimply wraps the calls in a stream like fashion.\n\nThe constructor of `JsonStream` either accepts a value to encode as JSON or an\ninstance of `BufferJsonEncoder` (which allows you to set the encoding options).\nYou can then operate on the stream using the methods provided by the PSR-7\ninterface. For example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$iterator = function () {\n    foreach (new DirectoryIterator(__DIR__) as $file) {\n        yield $file-\u003egetFilename();\n    }\n};\n\n$encoder = (new \\Violet\\StreamingJsonEncoder\\BufferJsonEncoder($iterator))\n    -\u003esetOptions(JSON_PRETTY_PRINT);\n\n$stream = new \\Violet\\StreamingJsonEncoder\\JsonStream($encoder);\n\nwhile (!$stream-\u003eeof()) {\n    echo $stream-\u003eread(1024 * 8);\n}\n```\n\nFor more information about PSR-7 streams, please refer to the [PSR-7\ndocumentation](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface).\n\n### How the encoder resolves values ###\n\nIn many ways, the Streaming JSON encoder is intended to work mostly as a drop in\nreplacement for `json_encode()`. However, since the encoder is intended to deal\nwith large data sets, there are some notable differences in how it handles\nobjects and arrays.\n\nFirst, to determine how to encode an object, the encoder will attempt to resolve\nthe object values in following ways:\n\n * For any object that implements `JsonSerializable` the implemented method\n   `jsonSerialize()` is called and return value is used instead.\n * Any `Closure` will be invoked and the return value will be used instead.\n   However, no other invokables are called in this manner.\n\nThe returned value is looped until it cannot be resolved further. After that,\na decision is made on whether the array or object is encoded as an array or as\nan object. The following logic is used:\n\n * Any empty array or array that has keys from 0 to n-1 in that order are\n   encoded as JSON arrays. All other arrays are encoded as JSON objects.\n * If an object implements `Traversable` and it either returns an **interger**\n   `0` as the first key or returns no values at all, it will be encoded as a\n   JSON array (regardless of other keys). All other objects implementing\n   `Traversable` are encoded as JSON objects.\n * Any other object, whether it's empty or whatever keys it mey have, is encoded\n   as a JSON object.\n\nNote, however, that if the JSON encoding option `JSON_FORCE_OBJECT` is used, all\nobjects and arrays are encoded as JSON objects.\n\nNote that all objects are traversed via a `foreach` statement. This means that\nall `Traversable` objects are encoded using the values returned by the iterator.\nFor other objects, this means that the public properties are used (as per\ndefault iteration behavior).\n\nAll other values (i.e. nulls, booleans, numbers and strings) are treated exactly\nthe same way as `json_encode()` does (and in fact, it's used to encode those\nvalues).\n\n### JSON encoding options ###\n\nBoth `BufferJsonEncoder` and `StreamJsonEncoder` have a method `setOptions()` to\nchange the JSON encoding options. The accepted options are the same as those\naccepted by `json_encode()` function. The encoder still internally uses the\n`json_encode()` method to encode values other than arrays or object. A few\noptions also have additional effects on the encoders:\n\n  * Using `JSON_FORCE_OBJECT` will force all arrays and objects to be encoded\n    as JSON objects similar to `json_encode()`.\n  * Using `JSON_PRETTY_PRINT` causes the encoder to output whitespace to in\n    order to make the output more readable. The used indentation can be changed\n    using the method `setIndent()` which accepts either a string argument to use\n    as the indent or an integer to indicate the number of spaces.\n  * Using `JSON_PARTIAL_OUTPUT_ON_ERROR` will cause the encoder to continue the\n    output despite encoding errors. Otherwise the encoding will halt and the\n    encoder will throw an `EncodingException`.\n\n## Credits ##\n\nThis library is Copyright (c) 2017-2022 Riikka Kalliomäki.\n\nSee LICENSE for license and copying information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviolet-php%2Fstreaming-json-encoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviolet-php%2Fstreaming-json-encoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviolet-php%2Fstreaming-json-encoder/lists"}