streaming json encoder
Version 1.1.5
streaming json encoder é uma biblioteca PHP que fornece um conjunto de classes para ajudar na codificação JSON de maneira streaming, ou seja, permitindo que você codifique o documento JSON pouco a pouco, em vez de codificar o documento inteiro de uma vez. Em comparação com a função json_encode integrada, existem duas vantagens principais:
Em outras palavras, o streaming json encoder pode fornecer o maior benefício quando você precisa lidar com grandes conjuntos de dados que, de outra forma, poderiam ocupar muita memória para serem processados.
Para aumentar a interoperabilidade, a biblioteca também fornece um fluxo compatível com PSR-7 para uso com estruturas e solicitações HTTP.
A documentação da API está disponível em: http://violet.riimu.net/api/streaming-json-encoder/
^1.0 ) A maneira mais fácil de instalar esta biblioteca é usar o Composer para lidar com suas dependências. Para instalar esta biblioteca via Composer, basta seguir estes dois passos:
Adquira o composer.phar executando a instalação da linha de comando do Composer na raiz do seu projeto.
Depois de executar o script de instalação, você deverá ter o arquivo composer.phar na raiz do projeto e poderá executar o seguinte comando:
php composer.phar require "violet/streaming-json-encoder:^1.1"
Após instalar esta biblioteca via Composer, você pode carregá-la incluindo o arquivo vendor/autoload.php que foi gerado pelo Composer durante a instalação.
Se você já está familiarizado com o uso do Composer, você pode alternativamente adicionar a biblioteca como uma dependência adicionando o seguinte arquivo composer.json ao seu projeto e executando o comando composer install :
{
"require" : {
"violet/streaming-json-encoder" : " ^1.1 "
}
} Se não desejar usar o Composer para carregar a biblioteca, você também pode fazer o download da biblioteca manualmente, baixando a versão mais recente e extraindo a pasta src para o seu projeto. Você pode então incluir o arquivo src/autoload.php fornecido para carregar as classes da biblioteca.
Observe que usar o Composer também baixará automaticamente as outras bibliotecas PHP necessárias. Se você instalar esta biblioteca manualmente, também precisará disponibilizar as outras bibliotecas necessárias.
Esta biblioteca oferece 3 maneiras principais diferentes de usar a biblioteca por meio das classes BufferJsonEncoder , StreamJsonEncoder e o fluxo compatível com PSR-7 JsonStream .
O codificador de buffer é mais útil quando você precisa gerar o documento JSON de uma forma que não envolva a passagem de retornos de chamada para manipular o JSON gerado.
A maneira mais fácil de usar o BufferJsonEncoder é instanciá-lo com o valor JSON para codificar e chamar o método encode() para retornar a saída inteira como uma string:
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder BufferJsonEncoder ([ ' array_value ' ]);
echo $ encoder -> encode (); A maneira mais útil de usar esse codificador, entretanto, é usá-lo como um iterador. À medida que o codificador implementa a interface Iterator , você pode simplesmente fazer um loop no JSON gerado com um loop foreach:
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder BufferJsonEncoder ( range ( 0 , 10 ));
foreach ( $ encoder as $ string ) {
echo $ string ;
}Também é importante notar que o codificador oferece suporte a iteradores para valores. Além do mais, qualquer encerramento passado para o codificador também será chamado e o valor de retorno usado como valor. O exemplo anterior também poderia ser escrito como:
<?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 ;
} Como observação lateral, o codificador também respeitará a interface JsonSerializable e chamará jsonSerialize para objetos que implementam a interface.
O codificador de fluxo funciona de forma muito semelhante ao BufferJsonEncoder , pois estende a mesma classe abstrata. No entanto, a principal diferença está em como eles lidam com a passagem da saída JSON.
O StreamJsonEncoder aceita um callable como o segundo argumento do construtor. Sempre que JSON precisa ser gerado, esse chamável é chamado com dois argumentos, a string real a ser gerada e o tipo do token a ser gerado (que é uma das constantes JsonToken ).
Se nenhum callable for passado, o StreamJsonEncoder simplesmente produzirá o JSON usando uma instrução echo. Por exemplo:
<?php
require ' vendor/autoload.php ' ;
$ encoder = new Violet StreamingJsonEncoder StreamJsonEncoder ([ ' array_value ' ]);
$ encoder -> encode (); O método encode() em StreamJsonEncoder retorna o número total de bytes passados para a saída. Esse codificador torna conveniente, por exemplo, gravar o JSON em um arquivo de maneira streaming. Por exemplo:
<?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 ); A classe stream fornece um StreamInterface compatível com PSR-7 para streaming de conteúdo JSON. Na verdade, ele usa o BufferJsonEncoder para fazer o trabalho pesado e simplesmente agrupa as chamadas em um fluxo semelhante a um stream.
O construtor de JsonStream aceita um valor para codificar como JSON ou uma instância de BufferJsonEncoder (que permite definir as opções de codificação). Você pode então operar no stream usando os métodos fornecidos pela interface PSR-7. Por exemplo:
<?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 );
}Para obter mais informações sobre fluxos PSR-7, consulte a documentação do PSR-7.
De muitas maneiras, o streaming json encoder destina-se a funcionar principalmente como um substituto para json_encode() . No entanto, como o codificador se destina a lidar com grandes conjuntos de dados, existem algumas diferenças notáveis na forma como ele lida com objetos e matrizes.
Primeiro, para determinar como codificar um objeto, o codificador tentará resolver os valores do objeto das seguintes maneiras:
JsonSerializable o método implementado jsonSerialize() é chamado e o valor de retorno é usado.Closure será invocado e o valor de retorno será usado em seu lugar. No entanto, nenhum outro invocável é chamado dessa maneira.O valor retornado é repetido até que não possa mais ser resolvido. Depois disso, é tomada uma decisão sobre se o array ou objeto é codificado como um array ou como um objeto. A seguinte lógica é usada:
Traversable e retornar um número inteiro 0 como a primeira chave ou não retornar nenhum valor, ele será codificado como uma matriz JSON (independentemente de outras chaves). Todos os outros objetos que implementam Traversable são codificados como objetos JSON. Observe, entretanto, que se a opção de codificação JSON JSON_FORCE_OBJECT for usada, todos os objetos e matrizes serão codificados como objetos JSON.
Observe que todos os objetos são percorridos por meio de uma instrução foreach . Isso significa que todos os objetos Traversable são codificados usando os valores retornados pelo iterador. Para outros objetos, isso significa que as propriedades públicas são usadas (conforme comportamento de iteração padrão).
Todos os outros valores (ou seja, nulos, booleanos, números e strings) são tratados exatamente da mesma maneira que json_encode() (e de fato, é usado para codificar esses valores).
Tanto BufferJsonEncoder quanto StreamJsonEncoder possuem um método setOptions() para alterar as opções de codificação JSON. As opções aceitas são as mesmas aceitas pela função json_encode() . O codificador ainda usa internamente o método json_encode() para codificar valores diferentes de arrays ou objetos. Algumas opções também têm efeitos adicionais nos codificadores:
JSON_FORCE_OBJECT forçará todos os arrays e objetos a serem codificados como objetos JSON semelhantes a json_encode() .JSON_PRETTY_PRINT faz com que o codificador gere espaços em branco para tornar a saída mais legível. O recuo usado pode ser alterado usando o método setIndent() que aceita um argumento de string para usar como recuo ou um número inteiro para indicar o número de espaços.JSON_PARTIAL_OUTPUT_ON_ERROR fará com que o codificador continue a saída apesar dos erros de codificação. Caso contrário, a codificação será interrompida e o codificador lançará uma EncodingException . Esta biblioteca tem Copyright (c) 2017-2022 Riikka Kalliomäki.
Consulte LICENÇA para obter informações sobre licença e cópia.
