PHPackages                             webdevcraft/jsonreader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. webdevcraft/jsonreader

ActiveLibrary[Parsing & Serialization](/categories/parsing)

webdevcraft/jsonreader
======================

JSON streaming reader (memory safety parser) with chunking option

0.2.0(9y ago)48.1k3[1 PRs](https://github.com/webdevcraft/jsonreader/pulls)MITPHP

Since Oct 28Pushed 8y ago1 watchersCompare

[ Source](https://github.com/webdevcraft/jsonreader)[ Packagist](https://packagist.org/packages/webdevcraft/jsonreader)[ RSS](/packages/webdevcraft-jsonreader/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (1)Versions (9)Used By (0)

JsonReader
==========

[](#jsonreader)

[![Build Status](https://camo.githubusercontent.com/55b721b38222e51b4e0fc00ad6530b2bada302849275603dc880f072971736cc/68747470733a2f2f7472617669732d63692e6f72672f77656264657663726166742f6a736f6e7265616465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/webdevcraft/jsonreader)

JSON streaming reader (memory safety parser) with chunking option

Purpose and Advantages
----------------------

[](#purpose-and-advantages)

1. **Memory safety** read of huge JSON files: solve "out of RAM" problem. Successfully tested with 1.5Gb JSON files
2. Possibility to split large JSON file to smaller **JSON chunks**
3. **Custom traverse** through JSON tree
4. Read **any JSON source**: file, string, resource, character iterator
5. Installation with **Composer**, no need any extra PHP extensions

Requirements
------------

[](#requirements)

PHP 5.6, 7.0

Installation
------------

[](#installation)

With Composer:

```
composer require webdevcraft/jsonreader
```

Basic Usage
-----------

[](#basic-usage)

JSON Reader iterates through JSON structure elements

Each `$reader->read()` iterates to next element until it returns *false* when finished

So common usage is:

```
while ($reader->read()) {
    // next element iteration
}
```

Reader provides information on each element:

1. **DEPTH** in JSON tree starting from 1: `$reader->getDepth()`
2. **STATE** (type of element): `$reader->getState()`. There is syntax sugar issers exist for each of states. State could be one of:

    - **Object Start**: *JsonReaderInterface::STATE\_OBJECT\_START* (or `$reder->isObjectStartState()`)
    - **Object Key**: *JsonReaderInterface::STATE\_OBJECT\_KEY* (or `$reder->isObjectKeyState()`)
    - **Object End** *JsonReaderInterface::STATE\_OBJECT\_END* (or `$reder->isObjectEndState()`)
    - **Array Start** *JsonReaderInterface::STATE\_ARRAY\_START* (or `$reder->isArrayStartState()`)
    - **Array End** *JsonReaderInterface::STATE\_ARRAY\_END* (or `$reder->isArrayEndState()`)
    - **Value** *JsonReaderInterface::STATE\_VALUE* (or `$reder->isValueState()`)
3. **VALUE** of element by `$reader->getValue()`. Types:

    1. For `$reader->getState() === JsonReaderInterface::STATE_VALUE` the type of value is automatically casted to PHP type: *string, int, float, boolean, null*
    2. For `JsonReaderInterface::STATE_OBJECT_KEY` state is always *string*
    3. For other states value is always *null*

**Example** of elements sequence for [test.json](https://github.com/webdevcraft/jsonreader/blob/master/tests/data/test.json) is presented in [JsonReaderTest.php::testReadTokens()](https://github.com/webdevcraft/jsonreader/blob/master/tests/JsonReaderTest.php)

Chunks Usage
------------

[](#chunks-usage)

In case if your code is already dependent on JSON string denormanization you could use JsonReader library for chunking of huge file onto smaller JSON strings

Just start buffering chunk on element position you wish by `$reader->startWriteChunk()` and get chunk by `$reader->finishWriteChunk()`. That returnes JSON chunk string and flushes buffer.

As chunk is buffered in memory make sure your JSON schema guarantees acceptable size of chunk

That's nice practice to wrap chunks retrieve to iterator

**Example** of [test.json](https://github.com/webdevcraft/jsonreader/blob/master/tests/data/test.json) chunking is presented in [JsonReaderTest.php::testChunks()](https://github.com/webdevcraft/jsonreader/blob/master/tests/JsonReaderTest.php)

Factory Usage
-------------

[](#factory-usage)

To create reader you have to use **JsonReaderFactory**

Example of JsonReader creating:

```
$factory = new JsonReaderFactory();
$reader = $factory->createByFilePath('/tmp/test.json');
```

Factory supports any sources by such methods:

1. **createByFilePath** by file path in local filesystem
2. **createByString** by JSON string passing
3. **createByResource** by opened resource link, for example with *fopen()*
4. **createByCharacterTraversable** - if options above do not suite your needs feel free to write your custom characters iterator using any source you have to deal with. For example you could iterate *PSR-7 Message\\StreamInterface::read($acceptableSize)* and iterate characters inside each of *read()*

[Example of characters iterators](https://github.com/webdevcraft/jsonreader/tree/master/src/CharacterIterator)

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity28

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

8

Last Release

3534d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/396fa1ae5c43ba8b8ee1f302f5ae907ffd09503cf98983115aa136a4caae9bea?d=identicon)[webdevcraft](/maintainers/webdevcraft)

---

Top Contributors

[![ibarabash](https://avatars.githubusercontent.com/u/8696071?v=4)](https://github.com/ibarabash "ibarabash (18 commits)")

---

Tags

streamjsonreaderjson-parsermemory safetyhuge jsonlarge json

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/webdevcraft-jsonreader/health.svg)

```
[![Health](https://phpackages.com/badges/webdevcraft-jsonreader/health.svg)](https://phpackages.com/packages/webdevcraft-jsonreader)
```

###  Alternatives

[mtdowling/jmespath.php

Declaratively specify how to extract elements from a JSON document

2.0k504.8M167](/packages/mtdowling-jmespathphp)[jms/serializer

Library for (de-)serializing data of any complexity; supports XML, and JSON.

2.3k141.9M929](/packages/jms-serializer)[jms/serializer-bundle

Allows you to easily serialize, and deserialize data of any complexity

1.8k92.4M680](/packages/jms-serializer-bundle)[cerbero/json-parser

Zero-dependencies pull parser to read large JSON from any source in a memory-efficient way.

806588.3k5](/packages/cerbero-json-parser)[colinodell/json5

UTF-8 compatible JSON5 parser for PHP

30525.1M57](/packages/colinodell-json5)[clue/ndjson-react

Streaming newline-delimited JSON (NDJSON) parser and encoder for ReactPHP.

15882.2M31](/packages/clue-ndjson-react)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)