README

PHP 简单库，用于管理 JSON 文件。

• 需求
• 安装
• 可用类
  • Json 类
• 使用的异常
• 用法
• 测试
• 待办事项
• 变更日志
• 贡献
• 赞助商
• 许可协议

需求

• 操作系统：Linux。

• PHP 版本：8.1 | 8.2。

安装

安装此扩展的首选方式是通过 Composer。

要安装 PHP JSON 库，只需

composer require josantonius/json

前面的命令将只安装必要的文件，如果您想 下载完整的源代码，请使用

composer require josantonius/json --prefer-source

您还可以使用 Git 克隆完整的仓库

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

可用类

Json 类

Josantonius\Json\Json

创建引用 JSON 文件的对象

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

获取 JSON 文件的路径

public readonly string $filepath;

检查 JSON 文件是否已经创建

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

获取 JSON 文件的内容

/**
 * @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;

设置 JSON 文件或其键的内容

/**
 * @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;

将提供的数据与 JSON 文件或其键的内容合并

/**
 * @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;

移除并获取 JSON 文件或其键中的最后一个元素

/**
 * @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;

将提供的数据添加到 JSON 文件或其键的内容末尾

/**
 * @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;

移除并获取 JSON 文件或其键中的第一个元素

/**
 * @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;

从 JSON 文件的内容中移除键及其值

/**
 * @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;

将提供的数据添加到 JSON 文件或其键的内容开头

/**
 * @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;

使用的异常

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

用法

此库的使用示例

获取 JSON 文件的路径

use Josantonius\Json\Json;

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

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

检查本地文件是否存在

use Josantonius\Json\Json;

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

$json->exists(); // bool

将 JSON 文件内容作为数组获取

file.json

{
    "foo": "bar"
}

index.php

use Josantonius\Json\Json;

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

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

将 JSON 文件内容作为对象获取

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" }

在 JSON 文件内容中设置空数组

index.php

use Josantonius\Json\Json;

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

$json->set();

file.json

[]

设置 JSON 文件的内容

index.php

use Josantonius\Json\Json;

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

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

file.json

{
    "foo": "bar"
}

使用点表示法设置 JSON 文件中键的内容

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"
        ]
    }
}

将提供的数据与 JSON 文件的内容合并

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"
}

使用点表示法将提供的数据与文件中键的内容合并

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"
        }
    ]
}

移除并获取 JSON 文件中的最后一个元素

file.json

[
    1,
    2,
    3
]

index.php

use Josantonius\Json\Json;

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

$json->pop(); // 3

file.json

[
    1,
    2
]

使用点表示法移除并获取文件中键的最后一个元素

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
    ]
}

将提供的数据添加到 JSON 文件内容的末尾

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"
    }
]

使用点表示法将提供的数据添加到文件中键的内容末尾

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"
            ]
        ]
    }
}

移除 JSON 文件内容中的第一个元素

file.json

[
    1,
    2,
    3
]

index.php

use Josantonius\Json\Json;

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

$json->shift(); // 1

file.json

[
    2,
    3
]

使用点表示法移除文件中键的第一个元素

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": [
            []
        ]
    }
}

从 JSON 文件的内容中移除字符串键及其值

file.json

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

index.php

use Josantonius\Json\Json;

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

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

file.json

{
    "foo": []
}

从 JSON 文件的内容中移除数字键及其值

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
}

从 JSON 文件的内容中移除数字键及其值并重新索引

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
]

将提供的数据添加到 JSON 文件内容的开头

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
]

使用点将提供的数据添加到文件中键的内容开头

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
            ]
        ]
    }
}

测试

要运行 测试，您只需要 composer 并执行以下操作

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

cd php-json

composer install

使用 PHPUnit 运行单元测试

composer phpunit

使用 PHPCS 运行代码标准测试

composer phpcs

运行 PHP Mess Detector 测试以检测代码风格的矛盾

composer phpmd

运行所有之前的测试

composer tests

待办事项

• 添加新功能
• 改进测试
• 改进文档
• 改进README文件中的英文翻译
• 重构禁用代码风格规则的代码（参见phpmd.xml和phpcs.xml）

变更日志

每个版本的详细更改记录在发布说明中。

贡献

在进行pull request、开始讨论或报告问题之前，请务必阅读贡献指南。

感谢所有贡献者！❤️

赞助商

如果这个项目帮助您减少了开发时间，您可以通过赞助我来支持我的开源工作 😊

许可协议

此存储库受MIT许可许可。

版权所有 © 2016-至今，Josantonius