README

我目前正在积极开发这个库，它可能不再工作！您可以委托我和其他领先的 Wikibase 专家进行 Wikibase 软件开发 或其他 Wikibase 服务。

JsonDumpReader 是一个 PHP 库，提供读取和遍历 Wikibase 存储库 JSON 导出中 Wikibase 实体的方法，例如 Wikidata JSON 导出。您可以在 Wikidata 导出下载页面 上找到有关格式的更多信息。

• 用法
• 安装
• 开发
• 发行说明
• 另请参阅

您可以为定制开发或 Wikibase 托管 而雇佣 作者 公司 Professional Wiki。

用法

所有服务都是通过 JsonDumpFactory 类构建的

use Wikibase\JsonDumpReader\JsonDumpFactory;
$factory = new JsonDumpFactory();

此库提供的两种类型的服务：实现 DumpReader 的服务和实现 Iterator 的服务。前者允许您请求导出的下一行。它们是最底层的，不同的实现支持不同的导出文件格式（如 .json 和 .json.bz2）。所有迭代器都依赖于一个 DumpReader，并允许您轻松遍历导出中的所有实体。它们在额外处理量上有所不同，从什么也不做（返回 JSON 字符串）到完全反序列化实体到 EntityDocument 对象。

从导出中读取一些行

$dumpReader = $factory->newExtractedDumpReader( '/tmp/wd-dump.json' );
echo 'First line: ' . $dumpReader->nextJsonLine();
echo 'Second line: ' . $dumpReader->nextJsonLine();

$dumpReader = $factory->newGzDumpReader( '/tmp/wd-dump.json.gz' );
echo 'First line: ' . $dumpReader->nextJsonLine();
echo 'Second line: ' . $dumpReader->nextJsonLine();

$dumpReader = $factory->newBz2DumpReader( '/tmp/wd-dump.json.bz2' );
echo 'First line: ' . $dumpReader->nextJsonLine();
echo 'Second line: ' . $dumpReader->nextJsonLine();

从上一个位置继续读取

$dumpReader = $factory->newGzDumpReader( '/tmp/wd-dump.json.gz' );
echo 'First line: ' . $dumpReader->nextJsonLine();
echo 'Second line: ' . $dumpReader->nextJsonLine();

$newReader = $factory->newGzDumpReader( '/tmp/wd-dump.json.gz' );
$newReader->seekToPosition( $dumpReader->getPosition() );

echo 'Third line: ' . $newReader->nextJsonLine();

遍历 JSON

$dumpReader = $factory->newGzDumpReader( '/tmp/wd-dump.json.gz' );
$dumpIterator = $factory->newStringDumpIterator( $dumpReader );

foreach ( $dumpIterator as $jsonLine ) {
	echo 'You can haz JSON: ' . $jsonLine;
}

创建 EntityDocument 迭代器

$dumpReader = $factory->newBz2DumpReader( '/tmp/wd-dump.json.bz2' );
$dumpIterator = $factory->newEntityDumpIterator( $dumpReader, /* Deserializer */ $entityDeserializer );

foreach ( $dumpIterator as $entityDocument ) {
	echo 'At entity ' . $entityDocument->getId()->getSerialization();
}

第二个参数需要是一个可以反序列化实体的 Deserializer 实例。这样一个实例通常是通过 Wikibase DataModel Serialization 库 构造的。有关如何操作的示例，请参阅 tests/integration/EntityDumpIteratorTest.php 文件。请注意，此代码有 其他依赖项。

组合迭代器

此库采用的迭代器方法是懒加载的，可以轻松与 PHP 提供的迭代器工具（如 LimitIterator 和 CallbackFilterIterator）结合使用。

更多文档和示例

要获取始终是最新的并且始终完全适用于您库版本的文档，请查看 src/JsonDumpFactory.php 中的公共方法。每个公共方法至少有一个测试，因此您可以在测试目录中找到好的示例。

安装

要在项目中使用 JsonDumpReader 库，只需将 jeroen/json-dump-reader 依赖项添加到您的项目 composer.json 文件中。以下是一个仅定义 JsonDumpReader 2.x 依赖项的最小 composer.json 文件示例

{
    "require": {
        "jeroen/json-dump-reader": "~2.0"
    }
}

支持的 PHP 版本

• 版本 2.x: 7.1 - 7.3+
• 版本 1.4: 5.6 - 7.2
• 版本 1.3: 5.5 - 7.2

使用 EntityDocument 安装

如果您想使用实体文档迭代器，您还需要安装创建导出文件的 Wikibase 所使用的 DataValue 库。对于 Wikidata 和典型的 Wikibase 安装，这些库包括

• DataValues Geo
• DataValues Number
• DataValues Time

您可以将这些库添加到 composer.json 中的 require 部分，如下所示。注意，所使用的版本截至 2018 年 8 月。您可以使用适合您的最新版本，因为这些库不受 JsonDumpReader 的限制。

        "data-values/geo": "~4.0|~3.0",
        "data-values/number": "~0.10.0",
        "data-values/time": "~1.0",

开发

在本地运行 CI 检查和测试

如果您已经在本地上安装了 PHP 和 Composer，则不需要 Docker，只需执行 composer 命令即可。

仅用于测试

composer test

仅用于样式检查

composer cs

用于完整 CI 运行

composer ci

Docker：安装

您可以通过使用 Docker 在没有本地 PHP 或 Composer 安装的情况下进行开发。使用以下命令安装它

sudo apt-get install docker docker-compose

Docker：运行 Composer

要使用 Composer 拉取项目依赖项，请运行

make composer install

您可以通过 make run 运行其他 Composer 命令，但目前这不支持参数标志。如果您需要执行此类命令，可以按照此格式进行

docker run --rm --interactive --tty --volume $PWD:/app -w /app\
 --volume ~/.composer:/composer --user $(id -u):$(id -g) composer composer install --no-scripts

其中 composer install --no-scripts 是正在运行的命令。

Docker：运行 CI 检查

要运行所有 CI 检查，包括 PHPUnit 测试、PHPCS 样式检查和覆盖率标签验证，请运行

make

Docker：运行测试

要仅运行 PHPUnit 测试，请运行

make test

要仅运行 PHPUnit 测试的子集或以其他方式传递标志给 PHPUnit，请运行

docker-compose run --rm app ./vendor/bin/phpunit --filter SomeClassNameOrFilter

发行说明

版本 2.0.0（2018-08-14）

• 添加了对 PHP 7.3 的支持
• 取消了对 PHP 5.6 和 PHP 7.0 的支持
• 添加了标量返回类型提示
  • 对扩展 DumpReader 或 SeekableDumpReader 的类的破坏性变更

版本 1.4.0（2017-03-03）

• 添加了对 PHP 7.1 和 PHP 7.2 的支持
• 取消了对 PHP 5.5 的支持

版本 1.3.0（2015-11-23）

• JsonDumpFactory::newGzDumpReader 现在接受一个可选的 $initialPosition 参数

版本 1.2.0（2015-11-23）

• 添加了 SeekableDumpReader 接口
  • JsonDumpFactory::newGzDumpReader 现在返回一个 SeekableDumpReader
  • JsonDumpFactory::newExtractedDumpReader 现在返回一个 SeekableDumpReader
• ExtractedDumpReader 现在是包私有（在 2.0 之前不会对其进行破坏性变更）

版本 1.1.0（2015-11-12）

• 添加了 JsonDumpFactory::newGzDumpReader 以支持 gzip 导出

版本 1.0.1（2015-11-10）

• 修复了通过 getPosition 重新启动 ExtractedDumpReader 时的 off-by-one 错误

版本 1.0.0（2015-11-08）

• 添加了 JsonDumpFactory
  • 添加了 JsonDumpFactory::newBz2DumpReader
  • 添加了 JsonDumpFactory::newExtractedDumpReader
  • 添加了 JsonDumpFactory::newStringDumpIterator
  • 添加了 JsonDumpFactory::newObjectDumpIterator
  • 添加了 JsonDumpFactory::newEntityDumpIterator
• 删除了 JsonDumpReader（现在为 JsonDumpFactory::newExtractedDumpReader）
• 删除了 JsonDumpIterator（现在为 JsonDumpFactory::newEntityDumpIterator）
• 添加了运行 PHPUnit、PHPCS、PHPMD 和标签覆盖验证的 ci 命令

版本 0.2.0（2015-09-29）

• 现在支持使用 Wikibase DataModel Serialization 2.x 进行安装
• 取消了对 Wikibase DataModel 版本的安装限制

版本 0.1.0（2014-10-22）

初始版本，包含

• JsonDumpReader 从导出中读取实体 JSON
• JsonDumpIterator 遍历导出，就像它是一个 EntityDocument 集合一样

另请参阅

• Replicator - 使用 JsonDumpReader 的 CLI 应用程序
• Wikibase 组件 - 用于处理 Wikibase/Wikidata 的各种库