indykoning/php-jsonl

PHP JSSONL library for fast JSON Lines parsing and writing.

1.0.0 2025-04-05 16:18 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^11.3.5
• squizlabs/php_codesniffer: ^3.12

MIT

• Indy Koning

• php
• json
• jsonlines
• JSON Lines
• jsonl

README

This package implements the JSON Lines format allowing you to encode and decode jsonl values. To take full advantage of the format we use PHP's Generators

Installation via Composer

composer require indykoning/php-jsonl

Usage

Decoding

To decode jsonl you can use the decode:

\Indykoning\Jsonl\Jsonl::decode($jsonl, $associative);

The jsonl variable can be a string of jsonl lines, an array of jsonl lines, or any Traversable. So anything that can be iterated over and contains valid json can be passed.

If you want to decode the jsonl from a file, or decode it as you're downloading it you can use decodeFromResource

\Indykoning\Jsonl\Jsonl::decodeFromResource($resource, $associative);

Some examples you can use for this are:

$data = \Indykoning\Jsonl\Jsonl::decodeFromResource(fopen('/tmp/data.jsonl', 'r'), true);

$data = \Indykoning\Jsonl\Jsonl::decodeFromResource(
    \Illuminate\Support\Facades\Http::get('https://example.com/data.jsonl')->resource()
);

Encoding

Encoding can be done by calling encode with a Traversable or array with the objects inside

\Indykoning\Jsonl\Jsonl::encode($array);

\Indykoning\Jsonl\Jsonl::encode([
    ['name' => 'Gilbert', 'session' => '2013', 'score' => 24, 'completed' => true],
    ['name' => 'Alexa', 'session' => '2013', 'score' => 29, 'completed' => true],
]);

Encoding also supports writing directly to a resource using encodeToResource:

\Indykoning\Jsonl\Jsonl::encodeToResource($resource, $array);

\Indykoning\Jsonl\Jsonl::encodeToResource(
    fopen('/tmp/data.jsonl', 'w'), 
    [
        ['name' => 'Gilbert', 'session' => '2013', 'score' => 24, 'completed' => true],
        ['name' => 'Alexa', 'session' => '2013', 'score' => 29, 'completed' => true],
    ]
);

Example using both

In practice this means you could proxy a theoretically infititely long file in json without issue.

function enrichData($data) 
{
    foreach($data as $object)
    {
        $object->enriched_data = EnrichmentModel::find($object->id)->toArray();

        yield $object;
    }
}

response()->streamDownload(
    function () {
        $data = \Indykoning\Jsonl\Jsonl::decodeFromResource(
            \Illuminate\Support\Facades\Http::get('https://example.com/data.jsonl')->resource()
        );

        $data = enrichData($data);

        $resource = fopen('php://output', 'w');
        \Indykoning\Jsonl\Jsonl::encodeToResource($resource, $data);
    },
    'data.jsonl',
    [
        'Content-Type' => 'application/jsonl'
    ]
);

With this code we'll be dealing with every json line one by one, enriching the data and passing it on to the client.

Running tests

composer test

License

This library is licensed under the MIT license. Please see LICENSE for more details.