PHP JSON library
, (*1)
PHP simple library for managing JSON files., (*2)
Requirements
-
Operating System: Linux., (*3)
-
PHP versions: 8.1 | 8.2., (*4)
Installation
The preferred way to install this extension is through Composer., (*5)
To install PHP JSON library, simply:, (*6)
composer require josantonius/json
The previous command will only install the necessary files,
if you prefer to download the full source code use:, (*7)
composer require josantonius/json --prefer-source
You can also clone the complete repository with Git:, (*8)
git clone https://github.com/josantonius/php-json.git
Available Classes
Json Class
Josantonius\Json\Json, (*9)
Create object referencing the JSON file:, (*10)
/**
* @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:, (*11)
public readonly string $filepath;
Check if the JSON file has already been created:, (*12)
/**
* @return bool True if the file exists at the specified filepath, false otherwise.
*/
public function exists(): bool;
Get the contents of the JSON file:, (*13)
/**
* @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:, (*14)
/**
* @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:, (*15)
/**
* @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:, (*16)
/**
* @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:, (*17)
/**
* @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:, (*18)
/**
* @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:, (*19)
/**
* @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:, (*20)
/**
* @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:, (*21)
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, (*22)
{
"foo": "bar"
}
index.php, (*23)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->get(); // ['foo' => 'bar']
Get the JSON file contents as object
file.json, (*24)
{
"foo": "bar"
}
index.php, (*25)
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, (*26)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->set();
file.json, (*27)
[]
Set the contents of a JSON file
index.php, (*28)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->set(['foo' => 'bar']);
file.json, (*29)
{
"foo": "bar"
}
Set the contents of a key within the JSON file using dot notation
file.json, (*30)
{
"foo": {
"bar": []
}
}
index.php, (*31)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->set('baz', 'foo.bar.0');
file.json, (*32)
{
"foo": {
"bar": [
"baz"
]
}
}
Merge the provided data with the contents of the JSON file
file.json, (*33)
{
"foo": "bar"
}
index.php, (*34)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->merge(['bar' => 'foo']);
file.json, (*35)
{
"foo": "bar",
"bar": "foo"
}
Merge the provided data with the contents of a key within the file using dot notation
file.json, (*36)
{
"foo": [
{
"bar": "baz"
}
]
}
index.php, (*37)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->merge(['baz' => 'bar'], 'foo.0');
file.json, (*38)
{
"foo": [
{
"bar": "baz",
"baz": "bar"
}
]
}
Remove and get the last element of a JSON file
file.json, (*39)
[
1,
2,
3
]
index.php, (*40)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->pop(); // 3
file.json, (*41)
[
1,
2
]
Remove and get the last element of a key within the file using dot notation
file.json, (*42)
{
"foo": [
1,
2,
3
]
}
index.php, (*43)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->pop(); // 3
file.json, (*44)
{
"foo": [
1,
2
]
}
Add the provided data to the end of the contents of a JSON file
file.json, (*45)
[
{
"name": "foo"
}
]
index.php, (*46)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->push(['name' => 'bar']);
file.json, (*47)
[
{
"name": "foo"
},
{
"name": "bar"
}
]
Add provided data to the end of the contents of a key within the file using dot notation
file.json, (*48)
{
"foo": {
"bar": [
[]
]
}
}
index.php, (*49)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->push('baz', 'foo.bar.0');
file.json, (*50)
{
"foo": {
"bar": [
[
"baz"
]
]
}
}
Remove and get the first element of the contents of a JSON file
file.json, (*51)
[
1,
2,
3
]
index.php, (*52)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->shift(); // 1
file.json, (*53)
[
2,
3
]
Remove and get the first item of the contents of a key within the file using dot notation
file.json, (*54)
{
"foo": {
"bar": [
[
1
]
]
}
}
index.php, (*55)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->shift('foo.bar.0'); // 1
file.json, (*56)
{
"foo": {
"bar": [
[]
]
}
}
Remove a string key and its value from the contents of a JSON file
file.json, (*57)
{
"foo": {
"bar": [
[]
]
}
}
index.php, (*58)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->unset('foo.bar');
file.json, (*59)
{
"foo": []
}
Remove a numeric key and its value from the contents of a JSON file
file.json, (*60)
[
1,
2,
3
]
index.php, (*61)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->unset('1');
file.json, (*62)
{
"0": 1,
"2": 3
}
Remove a numeric key and its value from the contents of a JSON file and re-index it
file.json, (*63)
[
1,
2,
3
]
index.php, (*64)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->unset('1', reindexed: true);
file.json, (*65)
[
1,
3
]
Add the provided data to the beginning of the contents of a JSON file
file.json, (*66)
[
1,
2,
3
]
index.php, (*67)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->unshift(0);
file.json, (*68)
[
0,
1,
2,
3
]
Add the provided data to the beginning of the contents of a key within the file using dot
file.json, (*69)
{
"foo": {
"bar": [
[
1
]
]
}
}
index.php, (*70)
use Josantonius\Json\Json;
$json = new Json('file.json');
$json->unshift(0, 'foo.bar.0');
file.json, (*71)
{
"foo": {
"bar": [
[
0,
1
]
]
}
}
Tests
To run tests you just need composer
and to execute the following:, (*72)
git clone https://github.com/josantonius/php-json.git
cd php-json
composer install
Run unit tests with PHPUnit:, (*73)
composer phpunit
Run code standard tests with PHPCS:, (*74)
composer phpcs
Run PHP Mess Detector tests to detect inconsistencies in code style:, (*75)
composer phpmd
Run all previous tests:, (*76)
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., (*77)
Contribution
Please make sure to read the Contributing Guide, before making a pull
request, start a discussion or report a issue., (*78)
Thanks to all contributors! :heart:, (*79)
If this project helps you to reduce your development time,
you can sponsor me to support my open source work :blush:, (*80)
License
This repository is licensed under the MIT License., (*81)
Copyright © 2016-present, Josantonius, (*82)
Wallogit.com
Josantonius