PHPackages                             josantonius/json - 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. josantonius/json

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

josantonius/json
================

PHP simple library for managing Json files.

v2.0.8(3y ago)1621.6k↓16.7%5[1 issues](https://github.com/josantonius/php-json/issues)10MITPHPPHP ^8.1

Since Dec 14Pushed 3y ago1 watchersCompare

[ Source](https://github.com/josantonius/php-json)[ Packagist](https://packagist.org/packages/josantonius/json)[ GitHub Sponsors](https://github.com/Josantonius)[ RSS](/packages/josantonius-json/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (21)Used By (10)

PHP JSON library
================

[](#php-json-library)

[![Latest Stable Version](https://camo.githubusercontent.com/02c1a126802fbde97d2840da819db841460edce133d539a4399c2602f522982e/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f4a736f6e2f762f737461626c65)](https://packagist.org/packages/josantonius/json)[![License](https://camo.githubusercontent.com/dcf4b041128a94ae87f25d840606aa2de78c085941b0e649021fbddbb4ca1520/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f6a736f6e2f6c6963656e7365)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/2d71a2ad3857729aa3bf4c6fb18d43ab8ee9ad3bdbd2a176ab727ea9826b19cf/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f6a736f6e2f646f776e6c6f616473)](https://packagist.org/packages/josantonius/json)[![CI](https://github.com/josantonius/php-json/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/josantonius/php-json/actions/workflows/ci.yml)[![CodeCov](https://camo.githubusercontent.com/4b189593f3ee49da8cb0bedaba0a212fdf9d90e606cd8fda38881a428381996d/68747470733a2f2f636f6465636f762e696f2f67682f6a6f73616e746f6e6975732f7068702d6a736f6e2f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/josantonius/php-json)[![PSR1](https://camo.githubusercontent.com/b502a899c9aec217e98971160f816f87346be272cf1a25cfa4793f2ee724bfc8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d312d6635373034362e737667)](https://www.php-fig.org/psr/psr-1/)[![PSR4](https://camo.githubusercontent.com/d1c090de87e968254a6658528f3bfe9c9dad422d6047fd1323dc211560182c01/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d342d3962353962362e737667)](https://www.php-fig.org/psr/psr-4/)[![PSR12](https://camo.githubusercontent.com/19c529c6dc0656dcc2a16c1a84af450b7bd0dc7b0571b8f17e4fc9f2414f8821/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d31322d3161626339632e737667)](https://www.php-fig.org/psr/psr-12/)

PHP simple library for managing JSON files.

---

- [Requirements](#requirements)
- [Installation](#installation)
- [Available Classes](#available-classes)
    - [Json Class](#json-class)
- [Exceptions Used](#exceptions-used)
- [Usage](#usage)
- [Tests](#tests)
- [TODO](#todo)
- [Changelog](#changelog)
- [Contribution](#contribution)
- [Sponsor](#sponsor)
- [License](#license)

---

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

[](#requirements)

- Operating System: Linux.
- PHP versions: 8.1 | 8.2.

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

[](#installation)

The preferred way to install this extension is through [Composer](http://getcomposer.org/download/).

To install **PHP JSON library**, simply:

```
composer require josantonius/json
```

The previous command will only install the necessary files, if you prefer to **download the full source code** use:

```
composer require josantonius/json --prefer-source
```

You can also **clone the complete repository** with Git:

```
git clone https://github.com/josantonius/php-json.git
```

Available Classes
-----------------

[](#available-classes)

### Json Class

[](#json-class)

`Josantonius\Json\Json`

Create object referencing the JSON file:

```
/**
 * @param string $filepath The path to the JSON file to be handled.
 */
public function __construct(public readonly string $filepath)
{
}
```

Get the path to the JSON file:

```
public readonly string $filepath;
```

Check if the JSON file has already been created:

```
/**
 * @return bool True if the file exists at the specified filepath, false otherwise.
 */
public function exists(): bool;
```

Get the contents of the JSON file:

```
/**
 * @param bool $asObject If true and the value is an array, it is returned as an object.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 *
 * @return mixed the contents of the JSON file.
 */
public function get(bool $asObject = false): mixed;
```

Set the contents of a JSON or a key within the file:

```
/**
 * @param mixed  $content The data that will be written to the file or a key within the file.
 * @param string $dot     The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws CreateFileException
 * @throws CreateDirectoryException
 * @throws NoIterableElementException
 *
 * @return mixed the content of the JSON file after the set operation.
 */
public function set(mixed $content = [], string $dot = null): array|bool|int|null|string;
```

Merge the provided data with the contents of a JSON file or a key within the file:

```
/**
 * @param mixed  $content The data that will be written to the file or a key within the file.
 * @param string $dot     The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 * @throws NoIterableElementException
 *
 * @return mixed the content of the JSON file after the merge operation.
 */
public function merge(array|object $content, string $dot = null): array;
```

Remove and get the last element of a JSON file or a key within the file:

```
/**
 * @param string $dot The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 * @throws NoIterableElementException
 *
 * @return mixed|null the last value of JSON file, or null if array is empty.
 */
public function pop(string $dot = null): mixed;
```

Add the provided data to the end of the contents of a JSON file or a key within the file:

```
/**
 * @param mixed  $content The data that will be written to the file or a key within the file.
 * @param string $dot     The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 * @throws NoIterableElementException
 *
 * @return mixed the content of the JSON file after the push operation.
 */
public function push(mixed $content, string $dot = null): array;
```

Remove and get the first element of a JSON file or a key within the file:

```
/**
 * @param string $dot The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 * @throws NoIterableElementException
 *
 * @return mixed|null the shifted value, or null if array is empty.
 */
public function shift(string $dot = null): mixed(mixed $content, string $dot = null): array;
```

Remove a key and its value from the contents of a JSON file:

```
/**
 * @param string $dot       The dot notation representing the key to be modified within the file.
 * @param bool   $reindexed If true, the array will be re-indexed.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 *
 * @return array the content of the JSON file after the unset operation.
 */
public function unset(string $dot, bool $reindexed = false): array;
```

Add the provided data to the beginning of the contents of a JSON file or a key within the file:

```
/**
 * @param mixed  $content The data that will be written to the file or a key within the file.
 * @param string $dot     The dot notation representing the key to be modified within the file.
 *
 * @throws GetFileException
 * @throws JsonErrorException
 * @throws NoIterableFileException
 * @throws NoIterableElementException
 *
 * @return mixed the content of the JSON file after the unshift operation.
 */
public function unshift(mixed $content, string $dot = null): mixed;
```

Exceptions Used
---------------

[](#exceptions-used)

```
use Josantonius\Json\Exceptions\GetFileException;           // if file reading failed
use Josantonius\Json\Exceptions\CreateFileException;        // if file creation failed
use Josantonius\Json\Exceptions\JsonErrorException;         // if the file contains invalid JSON
use Josantonius\Json\Exceptions\NoIterableFileException;    // if the file isn't a JSON array
use Josantonius\Json\Exceptions\CreateDirectoryException;   // if directory creation failed
use Josantonius\Json\Exceptions\NoIterableElementException; // if $dot isn't an array location
```

Usage
-----

[](#usage)

Example of use for this library:

### Get the path of the JSON file

[](#get-the-path-of-the-json-file)

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->filepath; // 'file.json'
```

### Check whether a local file exists

[](#check-whether-a-local-file-exists)

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->exists(); // bool
```

### Get the JSON file contents as array

[](#get-the-json-file-contents-as-array)

**`file.json`**

```
{
    "foo": "bar"
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->get(); // ['foo' => 'bar']
```

### Get the JSON file contents as object

[](#get-the-json-file-contents-as-object)

**`file.json`**

```
{
    "foo": "bar"
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->get(asObject: true); // object(stdClass) { ["foo"] => string(3) "bar" }
```

### Set an empty array in the JSON file contents

[](#set-an-empty-array-in-the-json-file-contents)

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->set();
```

**`file.json`**

```
[]
```

### Set the contents of a JSON file

[](#set-the-contents-of-a-json-file)

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->set(['foo' => 'bar']);
```

**`file.json`**

```
{
    "foo": "bar"
}
```

### Set the contents of a key within the JSON file using dot notation

[](#set-the-contents-of-a-key-within-the-json-file-using-dot-notation)

**`file.json`**

```
{
    "foo": {
        "bar": []
    }
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->set('baz', 'foo.bar.0');
```

**`file.json`**

```
{
    "foo": {
        "bar": [
            "baz"
        ]
    }
}
```

### Merge the provided data with the contents of the JSON file

[](#merge-the-provided-data-with-the-contents-of-the-json-file)

**`file.json`**

```
{
    "foo": "bar"
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->merge(['bar' => 'foo']);
```

**`file.json`**

```
{
    "foo": "bar",
    "bar": "foo"
}
```

### Merge the provided data with the contents of a key within the file using dot notation

[](#merge-the-provided-data-with-the-contents-of-a-key-within-the-file-using-dot-notation)

**`file.json`**

```
{
    "foo": [
        {
            "bar": "baz"
        }
    ]
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->merge(['baz' => 'bar'], 'foo.0');
```

**`file.json`**

```
{
    "foo": [
        {
            "bar": "baz",
            "baz": "bar"
        }
    ]
}
```

### Remove and get the last element of a JSON file

[](#remove-and-get-the-last-element-of-a-json-file)

**`file.json`**

```
[
    1,
    2,
    3
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->pop(); // 3
```

**`file.json`**

```
[
    1,
    2
]
```

### Remove and get the last element of a key within the file using dot notation

[](#remove-and-get-the-last-element-of-a-key-within-the-file-using-dot-notation)

**`file.json`**

```
{
    "foo": [
        1,
        2,
        3
    ]
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->pop(); // 3
```

**`file.json`**

```
{
    "foo": [
        1,
        2
    ]
}
```

### Add the provided data to the end of the contents of a JSON file

[](#add-the-provided-data-to-the-end-of-the-contents-of-a-json-file)

**`file.json`**

```
[
    {
        "name": "foo"
    }
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->push(['name'  => 'bar']);
```

**`file.json`**

```
[
    {
        "name": "foo"
    },
    {
        "name": "bar"
    }
]
```

### Add provided data to the end of the contents of a key within the file using dot notation

[](#add-provided-data-to-the-end-of-the-contents-of-a-key-within-the-file-using-dot-notation)

**`file.json`**

```
{
    "foo": {
        "bar": [
            []
        ]
    }
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->push('baz', 'foo.bar.0');
```

**`file.json`**

```
{
    "foo": {
        "bar": [
            [
                "baz"
            ]
        ]
    }
}
```

### Remove and get the first element of the contents of a JSON file

[](#remove-and-get-the-first-element-of-the-contents-of-a-json-file)

**`file.json`**

```
[
    1,
    2,
    3
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->shift(); // 1
```

**`file.json`**

```
[
    2,
    3
]
```

### Remove and get the first item of the contents of a key within the file using dot notation

[](#remove-and-get-the-first-item-of-the-contents-of-a-key-within-the-file-using-dot-notation)

**`file.json`**

```
{
    "foo": {
        "bar": [
            [
                1
            ]
        ]
    }
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->shift('foo.bar.0'); // 1
```

**`file.json`**

```
{
    "foo": {
        "bar": [
            []
        ]
    }
}
```

### Remove a string key and its value from the contents of a JSON file

[](#remove-a-string-key-and-its-value-from-the-contents-of-a-json-file)

**`file.json`**

```
{
    "foo": {
        "bar": [
            []
        ]
    }
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->unset('foo.bar');
```

**`file.json`**

```
{
    "foo": []
}
```

### Remove a numeric key and its value from the contents of a JSON file

[](#remove-a-numeric-key-and-its-value-from-the-contents-of-a-json-file)

**`file.json`**

```
[
    1,
    2,
    3
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->unset('1');
```

**`file.json`**

```
{
    "0": 1,
    "2": 3
}
```

### Remove a numeric key and its value from the contents of a JSON file and re-index it

[](#remove-a-numeric-key-and-its-value-from-the-contents-of-a-json-file-and-re-index-it)

**`file.json`**

```
[
    1,
    2,
    3
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->unset('1', reindexed: true);
```

**`file.json`**

```
[
    1,
    3
]
```

### Add the provided data to the beginning of the contents of a JSON file

[](#add-the-provided-data-to-the-beginning-of-the-contents-of-a-json-file)

**`file.json`**

```
[
    1,
    2,
    3
]
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->unshift(0);
```

**`file.json`**

```
[
    0,
    1,
    2,
    3
]
```

### Add the provided data to the beginning of the contents of a key within the file using dot

[](#add-the-provided-data-to-the-beginning-of-the-contents-of-a-key-within-the-file-using-dot)

**`file.json`**

```
{
    "foo": {
        "bar": [
            [
                1
            ]
        ]
    }
}
```

**`index.php`**

```
use Josantonius\Json\Json;

$json = new Json('file.json');

$json->unshift(0, 'foo.bar.0');
```

**`file.json`**

```
{
    "foo": {
        "bar": [
            [
                0,
                1
            ]
        ]
    }
}
```

Tests
-----

[](#tests)

To run [tests](tests) you just need [composer](http://getcomposer.org/download/)and to execute the following:

```
git clone https://github.com/josantonius/php-json.git
```

```
cd php-json
```

```
composer install
```

Run unit tests with [PHPUnit](https://phpunit.de/):

```
composer phpunit
```

Run code standard tests with [PHPCS](https://github.com/squizlabs/PHP_CodeSniffer):

```
composer phpcs
```

Run [PHP Mess Detector](https://phpmd.org/) tests to detect inconsistencies in code style:

```
composer phpmd
```

Run all previous tests:

```
composer tests
```

TODO
----

[](#todo)

- Add new feature
- Improve tests
- Improve documentation
- Improve English translation in the README file
- Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)

Changelog
---------

[](#changelog)

Detailed changes for each release are documented in the [release notes](https://github.com/josantonius/php-json/releases).

Contribution
------------

[](#contribution)

Please make sure to read the [Contributing Guide](.github/CONTRIBUTING.md), before making a pull request, start a discussion or report a issue.

Thanks to all [contributors](https://github.com/josantonius/php-json/graphs/contributors)! ❤️

Sponsor
-------

[](#sponsor)

If this project helps you to reduce your development time, [you can sponsor me](https://github.com/josantonius#sponsor) to support my open source work 😊

License
-------

[](#license)

This repository is licensed under the [MIT License](LICENSE).

Copyright © 2016-present, [Josantonius](https://github.com/josantonius#contact)

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity36

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 98.1% 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 ~123 days

Recently: every ~40 days

Total

19

Last Release

1224d ago

Major Versions

1.2.0 → 2.0.02022-06-16

PHP version history (4 changes)1.0.0PHP >=7.0

1.1.1PHP ^5.6 || ^7.0

1.2.0PHP ^8.0

v2.0.8PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/4b221283501ec8a9cbaefaf27821a91ae8ddd33bddf1fccc6c6815b7ad216ff1?d=identicon)[Josantonius](/maintainers/Josantonius)

---

Top Contributors

[![josantonius](https://avatars.githubusercontent.com/u/18104336?v=4)](https://github.com/josantonius "josantonius (157 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (3 commits)")

---

Tags

composerjsonphpphp-jsonphpjsonfile-to-arrayarray-to-file

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/josantonius-json/health.svg)

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

###  Alternatives

[adhocore/json-fixer

Fix/repair truncated JSON data

51543.2k2](/packages/adhocore-json-fixer)[m1/vars

Vars is a simple to use and easily extendable configuration loader with in built loaders for ini, json, PHP, toml, XML and yaml/yml file types. It also comes with in built support for Silex and more frameworks to come soon.

69124.2k1](/packages/m1-vars)[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6115.6k](/packages/sbsaga-toon)[blancks/fast-jsonpatch-php

Class designed to efficiently handle JSON Patch operations in accordance with the RFC 6902 specification

396.4k](/packages/blancks-fast-jsonpatch-php)

PHPackages © 2026

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