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。
有關許可證和複製信息，請參閱許可證。
