README

JSON Parser是一个流式JSON解析库。它返回的结果与\json_decode('some-string', true, 512, JSON_UNESCAPED_SLASHES)相同。

当需要解析多个MiB大小的JSON时，您可能想使用这个库，因为\json_decode()在内存中处理时会消耗大量的内存。如果使用得当（这并不困难，见下文），该库的内存使用量是恒定的，不受JSON字符串大小的限制。

对于小于~1 MiB的小JSON字符串，您可能不想使用这个库，因为\json_decode()大约快50倍。虽然我旨在提高性能，但C实现的\json_decode()始终比这个PHP实现快。

需求

• PHP >= 7.1

这就是全部。然而，使用mb_string扩展可以提高性能。

安装

使用Composer安装库。

composer require umulmrum/json-parser

状态

这个库处于测试版状态。单元测试的代码覆盖率很高，并且该库已在生产中使用，但尚未被认为稳定；鼓励您测试它并报告问题。

使用

<?php

include __DIR__.'/vendor/autoload.php';

$parser = umulmrum\JsonParser\JsonParser::fromFile('/path/to/file.json');
foreach ($parser->generate() as $value) {
    var_dump($value);
}

每个有效的JSON字符串都由一个根数组或一个包含值的根对象组成。generate()方法逐个返回这些顶级值。每个返回值都是一个包含单个键/值对的PHP数组；键是

• 如果根元素是对象，则为顶级值的键。
• 如果根元素是数组，则为顶级值的索引。

然后可以消耗这些值（例如，持久化、打印或通过AMQP发送）并在之后丢弃。

如果JSON字符串是一个空对象或数组，则返回一个空数组。

如果JSON字符串为空或只包含空白，则返回null。

在错误情况下，会抛出以下异常之一

• \Umulmrum\JsonParser\InvalidJsonException如果在遇到无效的JSON。异常提供了有关错误发生时JSON字符串的行和列的信息（有时这个信息会相差一行或一列）。
• \Umulmrum\JsonParser\DataSource\DataSourceException如果由于任何原因无法读取源文件。

如果没有抛出异常，则可以“信任”结果（即无需检查之后的错误，如\json_last_error()）。

替代用法

或者，从JSON字符串实例化解析器

$parser = umulmrum\JsonParser\JsonParser::fromString('["test"]');

请注意，这不会非常节省内存，因为PHP为字符串使用了大量的内存。只要可能，推荐使用fromFile()工厂方法。

JsonParser也可以通过调用all()返回完整内容（但由于内存问题，不推荐这样做）。

定制

内部，JsonParser使用一个实现了\Umulmrum\JsonParser\DataSource\DataSourceInterface的实现来接收要解析的字符。JsonParser的工厂方法是简单的便利方法，用于处理数据源的实例化，但可以手动调用构造函数，传递数据源，从而可以使用自定义数据源实现。有关详细信息，请参阅\Umulmrum\JsonParser\DataSource\DataSourceInterface的docblocks。您可能希望扩展包含一些便利方法的\Umulmrum\JsonParser\DataSource\AbstractDataSource。

上一节中的示例可以写成以下形式

$parser = new Umulmrum\JsonParser\JsonParser(new \Umulmrum\JsonParser\DataSource\FileDataSource('["test"]'));

向下兼容性

这个库遵循语义版本控制，因此只有在主要版本中（在达到1.0.0之前的次要版本中）才会引入破坏性的更改。公共API包括所有类，除了

• 所有标记为 @internal 的内容
• 测试

贡献

非常欢迎贡献。提交 PR 时请遵循以下规则

• 模仿现有代码的风格和结构。
• 为所有代码添加单元测试。
• 使用 Symfony 代码风格（php-cs-fixer，此存储库中的 .php_cs.dist 规则集）。

通过提交 PR，您同意您提供的所有代码可以在 MIT 许可证下使用。

许可证

本库采用 MIT 许可证。有关详细信息，请参阅 LICENSE。