Загрузка streaming json encoder - Загрузка streaming json encoder

streaming json encoder

Другие категории

Version 1.1.5

Скачать

streaming json encoder

streaming json encoder — это библиотека PHP, которая предоставляет набор классов, помогающих кодировать JSON потоковым способом, т. е. позволяет вам кодировать документ JSON постепенно, а не кодировать весь документ сразу. По сравнению со встроенной функцией json_encode есть два основных преимущества:

Вам не нужно будет загружать весь набор данных в память, поскольку кодировщик поддерживает перебор как массивов, так и любых итераторов, например генераторов.
Вам не нужно будет загружать весь полученный JSON-документ в память, поскольку JSON-документ будет закодирован значение за значением и можно будет выводить закодированный документ по частям.

Другими словами, streaming json encoder может обеспечить наибольшую выгоду, когда вам нужно обрабатывать большие наборы данных, которые в противном случае могут потребовать слишком много памяти для обработки.

Чтобы повысить совместимость, библиотека также предоставляет поток, совместимый с PSR-7, для использования с платформами и HTTP-запросами.

Документация по API доступна по адресу: http://violet.riimu.net/api/streaming-json-encoder/.

Требования

Минимальная поддерживаемая версия PHP — 5.6.
Библиотека зависит от следующих внешних библиотек PHP:
- psr/http-сообщение ( ^1.0 )

Установка

Установка с помощью Composer

Самый простой способ установить эту библиотеку — использовать Composer для обработки ваших зависимостей. Чтобы установить эту библиотеку через Composer, просто выполните следующие два шага:

Получите composer.phar , запустив установку Composer из командной строки в корне вашего проекта.
После запуска сценария установки файл composer.phar должен находиться в корне вашего проекта, и вы можете выполнить следующую команду:
```
 php composer.phar require "violet/streaming-json-encoder:^1.1"
```

После установки этой библиотеки через Composer вы можете загрузить ее, включив vendor/autoload.php , созданный Composer во время установки.

Добавление библиотеки в качестве зависимости

Если вы уже знакомы с тем, как использовать Composer, вы также можете добавить библиотеку в качестве зависимости, добавив в свой проект следующий файл composer.json и выполнив команду composer install :

{
    "require" : {
        "violet/streaming-json-encoder" : " ^1.1 "
    }
}

Ручная установка

Если вы не хотите использовать Composer для загрузки библиотеки, вы также можете загрузить библиотеку вручную, загрузив последнюю версию и распаковав папку src в свой проект. Затем вы можете включить предоставленный файл src/autoload.php для загрузки классов библиотеки.

Обратите внимание, что использование Composer также автоматически загрузит другие необходимые библиотеки PHP. Если вы устанавливаете эту библиотеку вручную, вам также необходимо будет сделать доступными другие необходимые библиотеки.

Использование

Эта библиотека предлагает 3 основных различных способа использования библиотеки через классы BufferJsonEncoder , StreamJsonEncoder и поток JsonStream , совместимый с PSR-7.

Использование BufferJsonEncoder

Кодировщик буфера наиболее полезен, когда вам нужно сгенерировать документ JSON способом, не требующим передачи обратных вызовов для обработки сгенерированного JSON.

Самый простой способ использовать BufferJsonEncoder — создать его экземпляр со значением JSON для кодирования и вызвать метод encode() чтобы вернуть весь вывод в виде строки:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  BufferJsonEncoder ([ ' array_value ' ]);
echo $ encoder -> encode ();

Однако наиболее полезный способ использования этого кодировщика — использовать его в качестве итератора. Поскольку кодировщик реализует интерфейс Iterator , вы можете просто перебрать сгенерированный JSON с помощью цикла foreach:

 <?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 для объектов, реализующих этот интерфейс.

Использование StreamJsonEncoder

Кодер потока работает очень похоже на BufferJsonEncoder , поскольку они расширяют тот же абстрактный класс. Однако ключевое различие заключается в том, как они обрабатывают передачу вывода JSON.

StreamJsonEncoder принимает вызываемый объект в качестве второго аргумента конструктора. Всякий раз, когда необходимо вывести JSON, этот вызываемый объект вызывается с двумя аргументами: фактической строкой для вывода и типом выводимого токена (который является одной из констант JsonToken ).

Если вызываемый объект не передается, StreamJsonEncoder просто выводит JSON с помощью оператора echo. Например:

 <?php

require ' vendor/autoload.php ' ;

$ encoder = new  Violet  StreamingJsonEncoder  StreamJsonEncoder ([ ' array_value ' ]);
$ encoder -> encode ();

Метод encode() в StreamJsonEncoder возвращает общее количество байтов, переданных на выход. Этот кодер позволяет удобно, например, записывать 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 );

Использование JsonStream

Класс потока предоставляет совместимый с 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 будет вызвано, и вместо него будет использовано возвращаемое значение. Однако никакие другие вызываемые объекты не вызываются таким образом.

Возвращенное значение зацикливается до тех пор, пока его невозможно будет разрешить дальше. После этого принимается решение о том, кодируется ли массив или объект как массив или как объект. Используется следующая логика:

Любой пустой массив или массив с ключами от 0 до n-1 в этом порядке кодируются как массивы JSON. Все остальные массивы кодируются как объекты JSON.
Если объект реализует Traversable и либо возвращает целое число 0 в качестве первого ключа, либо вообще не возвращает значений, он будет закодирован как массив JSON (независимо от других ключей). Все остальные объекты, реализующие Traversable кодируются как объекты JSON.
Любой другой объект, будь то пустой или какие-либо ключи, которые у него есть, кодируется как объект JSON.

Однако обратите внимание: если используется опция кодирования JSON JSON_FORCE_OBJECT , все объекты и массивы кодируются как объекты JSON.

Обратите внимание, что все объекты просматриваются с помощью оператора foreach . Это означает, что все объекты Traversable кодируются с использованием значений, возвращаемых итератором. Для других объектов это означает, что используются общедоступные свойства (согласно поведению итерации по умолчанию).

Все остальные значения (т. е. значения NULL, логические значения, числа и строки) обрабатываются точно так же, как и json_encode() (и фактически он используется для кодирования этих значений).

Параметры кодирования JSON

И BufferJsonEncoder , и StreamJsonEncoder имеют метод setOptions() для изменения параметров кодирования JSON. Принимаемые параметры такие же, как и у функции json_encode() . Кодировщик по-прежнему внутренне использует метод json_encode() для кодирования значений, отличных от массивов или объектов. Некоторые параметры также оказывают дополнительное влияние на кодеры:

Использование JSON_FORCE_OBJECT приведет к принудительному кодированию всех массивов и объектов как объектов JSON, аналогично json_encode() .
Использование JSON_PRETTY_PRINT заставляет кодировщик выводить пробелы, чтобы сделать вывод более читабельным. Используемый отступ можно изменить с помощью метода setIndent() который принимает либо строковый аргумент, используемый в качестве отступа, либо целое число, указывающее количество пробелов.
Использование JSON_PARTIAL_OUTPUT_ON_ERROR приведет к тому, что кодировщик продолжит вывод, несмотря на ошибки кодирования. В противном случае кодирование прекратится, и кодер выдаст исключение EncodingException .