stolt/json-lines

Library for the JSON Lines text file format.

v4.1.0 2024-12-09 17:11 UTC

Requires

• php: >=8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpunit/phpunit: 8.*
• stolt/lean-package-validator: ^3.0

Suggests

• ext-zlib: Allow gzip compression of JSON Lines when writing to a file

MIT

• Raphael Stolt

• json
• jsonlines

README

This is a library to enline to the JSON Lines format and to deline back from it to JSON.

Installation via Composer

composer require stolt/json-lines

Usage

To enline a data structure into JSON Lines use the enline method.

$jsonLines = (new JsonLines())->enline([
    ["one" => 1, "two" => 2],
    ["three" => 3, "four" => 4, "five" => 5],
    ["six" => 6, "seven" => 7, "key" => "value"],
    ["nested" => ["a", "b", "c"]],
]);
var_dump($jsonLines);

Which will give you the following JSON Lines string.

string(107) "{"one":1,"two":2}
{"three":3,"four":4,"five":5}
{"six":6,"seven":7,"key":"value"}
{"nested":["a","b","c"]}
"

To enline a data structure into a JSON Lines file use the enlineToFile method, adding the gz extension will gzip compress the JSON Lines as shown next.

(new JsonLines())->enlineToFile([
    ["one" => 1, "two" => 2],
    ["three" => 3, "four" => 4, "five" => 5],
    ["six" => 6, "seven" => 7, "key" => "value"],
    ["nested" => ["a", "b", "c"]],
    'out.jsonl.gz'
]);

To deline JSON Lines back into JSON use the deline method.

$json = (new JsonLines())->deline('{"one":1,"two":2}
{"three":3,"four":4,"five":5}
{"six":6,"seven":7,"key":"value"}
{"nested":["a","b","c"]}'
);
var_dump($json)

Which will give you the following JSON string, which is only beautified here to illustrate the data structure.

string(287) "[
    {
        "one": 1,
        "two": 2
    },
    {
        "three": 3,
        "four": 4,
        "five": 5
    },
    {
        "six": 6,
        "seven": 7,
        "key": "value"
    },
    {
        "nested": [
            "a",
            "b",
            "c"
        ]
    }
]"

To deline a complete JSON Lines file back into JSON use the delineFromFile method.

$json = (new JsonLines())->delineFromFile('/path/to/enlined.jsonl');

To deline a complete JSON Lines file line-by-line, use the delineEachLineFromFile method. This allows to iterate over a large file without storing the entire delined file in memory.

$json_lines = (new JsonLines())->delineEachLineFromFile('/path/to/enlined.jsonl');
foreach ($json_lines as $json_line) {
    var_dump($json_line);
}

Running tests

composer test

License

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

Changelog

Please see CHANGELOG for more details.

Contributing

Please see CONTRIBUTING for more details.