README

PHP simple library for managing JSON files.

• Requirements
• Installation
• Available Classes
  • Json Class
• Exceptions Used
• Usage
• Tests
• TODO
• Changelog
• Contribution
• Sponsor
• License

Requirements

• Operating System: Linux.

• PHP versions: 8.1 | 8.2.

Installation

The preferred way to install this extension is through Composer.

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

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

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

Example of use for this library:

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

use Josantonius\Json\Json;

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

$json->exists(); // bool

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

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

index.php

use Josantonius\Json\Json;

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

$json->set();

file.json

[]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To run tests you just need composer and to execute the following:

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

cd php-json

composer install

Run unit tests with PHPUnit:

composer phpunit

Run code standard tests with PHPCS:

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:

composer phpmd

Run all previous tests:

composer tests

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

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2016-present, Josantonius