streaming json encoder
Version 1.1.5
streaming json encoder是一个 PHP 库，它提供了一组类来帮助以流式方式编码 JSON，即允许您逐位编码 JSON 文档，而不是一次编码整个文档。与内置的json_encode函数相比，主要有两个优点：
换句话说，当您需要处理大型数据集（否则可能会占用太多内存来处理）时， streaming json encoder可以提供最大的好处。
为了提高互操作性，该库还提供了 PSR-7 兼容流以与框架和 HTTP 请求一起使用。
API 文档位于：http://violet.riimu.net/api/streaming-json-encoder/
^1.0 ) 安装此库的最简单方法是使用 Composer 来处理依赖项。要通过 Composer 安装此库，只需执行以下两个步骤：
通过在项目根目录中运行 Composer 命令行安装来获取composer.phar 。
运行安装脚本后，项目根目录中应该有composer.phar文件，并且可以运行以下命令：
php composer.phar require "violet/streaming-json-encoder:^1.1"
通过 Composer 安装此库后，您可以通过包含 Composer 在安装过程中生成的vendor/autoload.php文件来加载该库。
如果您已经熟悉如何使用 Composer，您也可以通过将以下composer.json文件添加到您的项目并运行composer install命令来将该库添加为依赖项：
{
"require" : {
"violet/streaming-json-encoder" : " ^1.1 "
}
}如果您不想使用 Composer 加载库，您还可以通过下载最新版本并将src文件夹解压到您的项目来手动下载库。然后，您可以包含提供的src/autoload.php文件来加载库类。
请注意，使用 Composer 还将自动下载其他所需的 PHP 库。如果您手动安装此库，您还需要使其他必需的库可用。
该库提供了 3 种主要的不同方法来通过类BufferJsonEncoder 、 StreamJsonEncoder和 PSR-7 兼容流JsonStream来使用该库。
当您需要以不涉及传递回调来处理生成的 JSON 的方式生成 JSON 文档时，缓冲区编码器最有用。
使用BufferJsonEncoder最简单的方法是使用要编码的 JSON 值实例化它，并调用encode()方法将整个输出作为字符串返回：
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder BufferJsonEncoder ([ ' array_value ' ]);
echo $ encoder -> encode ();然而，使用此编码器的最有用方法是将其用作迭代器。由于编码器实现了Iterator接口，您可以简单地使用 foreach 循环遍历生成的 JSON：
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder BufferJsonEncoder ( range ( 0 , 10 ));
foreach ( $ encoder as $ string ) {
echo $ string ;
}还值得注意的是，编码器支持值的迭代器。更重要的是，任何传递给编码器的闭包也将被调用，并且返回值将用作值。前面的例子也可以写成：
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder BufferJsonEncoder ( function () {
for ( $ i = 0 ; $ i <= 10 ; $ i ++) {
yield $ i ;
}
});
foreach ( $ encoder as $ string ) {
echo $ string ;
}附带说明一下，编码器也将遵循JsonSerializable接口，并将为实现该接口的对象调用jsonSerialize 。
流编码器的工作方式与BufferJsonEncoder非常相似，因为它们扩展了相同的抽象类。然而，关键的区别在于它们如何处理传递 JSON 输出。
StreamJsonEncoder接受可调用对象作为第二个构造函数参数。每当需要输出 JSON 时，都会使用两个参数调用此可调用函数，即要输出的实际字符串和要输出的令牌的类型（这是JsonToken常量之一）。
如果没有传递可调用对象，StreamJsonEncoder 将仅使用 echo 语句输出 JSON。例如：
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder StreamJsonEncoder ([ ' array_value ' ]);
$ encoder -> encode (); StreamJsonEncoder中的encode()方法返回传递给输出的字节总数。例如，该编码器可以方便地将 JSON 以流式方式写入文件。例如：
<?php
require ' vendor/autoload.php ' ;
$ fp = fopen ( ' test.json ' , ' wb ' );
$ encoder = new Violet StreamingJsonEncoder StreamJsonEncoder (
range ( 1 , 100 ),
function ( $ json ) use ( $ fp ) {
fwrite ( $ fp , $ json );
}
);
$ encoder -> encode ();
fclose ( $ fp ); Stream 类提供了一个与 PSR-7 兼容的StreamInterface ，用于流式传输 JSON 内容。它实际上使用BufferJsonEncoder来完成艰苦的工作，并像时尚一样将调用包装在流中。
JsonStream的构造函数接受编码为 JSON 的值或BufferJsonEncoder的实例（它允许您设置编码选项）。然后，您可以使用 PSR-7 接口提供的方法对流进行操作。例如：
<?php
require ' vendor/autoload.php ' ;
$ iterator = function () {
foreach ( new DirectoryIterator ( __DIR__ ) as $ file ) {
yield $ file -> getFilename ();
}
};
$ encoder = ( new Violet StreamingJsonEncoder BufferJsonEncoder ( $ iterator ))
-> setOptions ( JSON_PRETTY_PRINT );
$ stream = new Violet StreamingJsonEncoder JsonStream ( $ encoder );
while (! $ stream -> eof ()) {
echo $ stream -> read ( 1024 * 8 );
}有关 PSR-7 流的更多信息，请参阅 PSR-7 文档。
在很多方面， streaming json encoder主要是作为json_encode()的替代品。然而，由于编码器旨在处理大型数据集，因此它处理对象和数组的方式存在一些显着差异。
首先，为了确定如何对对象进行编码，编码器将尝试通过以下方式解析对象值：
JsonSerializable的对象，都会调用已实现的方法jsonSerialize()并使用返回值。Closure都将被调用，并且将使用返回值。但是，不会以这种方式调用其他可调用项。返回的值将被循环，直到无法进一步解析为止。之后，决定将数组或对象编码为数组还是对象。使用以下逻辑：
Traversable并且它返回一个整数0作为第一个键或者根本不返回任何值，那么它将被编码为 JSON 数组（无论其他键如何）。所有其他实现Traversable对象都被编码为 JSON 对象。但请注意，如果使用 JSON 编码选项JSON_FORCE_OBJECT ，则所有对象和数组都将编码为 JSON 对象。
请注意，所有对象都是通过foreach语句遍历的。这意味着所有Traversable对象都使用迭代器返回的值进行编码。对于其他对象，这意味着使用公共属性（根据默认迭代行为）。
所有其他值（即空值、布尔值、数字和字符串）的处理方式与json_encode()完全相同（事实上，它用于对这些值进行编码）。
BufferJsonEncoder和StreamJsonEncoder都有一个方法setOptions()来更改 JSON 编码选项。接受的选项与json_encode()函数接受的选项相同。编码器内部仍然使用json_encode()方法对数组或对象以外的值进行编码。一些选项还会对编码器产生额外影响：
JSON_FORCE_OBJECT将强制所有数组和对象编码为类似于json_encode() JSON 对象。JSON_PRETTY_PRINT会导致编码器输出空格，以使输出更具可读性。可以使用setIndent()方法更改所使用的缩进，该方法接受用作缩进的字符串参数或指示空格数的整数。JSON_PARTIAL_OUTPUT_ON_ERROR将导致编码器在编码错误的情况下继续输出。否则编码将停止并且编码器将抛出EncodingException 。 该库版权所有 (c) 2017-2022 Riikka Kalliomäki。
有关许可证和复制信息，请参阅许可证。
