README

这是一个简单且人性化的库，适用于API服务器（php提供json）。

它允许您根据JSON:API v1.1标准生成json输出，同时对于不了解jsonapi标准的人来说也容易理解。

JSON:API标准使得客户端能够在一个调用中获取多个资源并理解它们之间的关系。更多关于它的信息可以在jsonapi.org上阅读。

安装

使用Composer require获取最新稳定版本

composer require alsvanzelf/jsonapi

该库支持并已在php版本5.6、7和8上进行测试。

从v1升级

如果您使用了该库的v1版本，请参阅UPGRADE_1_TO_2.md了解如何升级。

入门

一个小型资源示例

use alsvanzelf\jsonapi\ResourceDocument;

$document = new ResourceDocument($type='user', $id=42);
$document->add('name', 'Zaphod Beeblebrox');
$document->add('heads', 2);
$document->sendResponse();

这将导致

{
	"jsonapi": {
		"version": "1.1"
	},
	"data": {
		"type": "user",
		"id": "42",
		"attributes": {
			"name": "Zaphod Beeblebrox",
			"heads": 2
		}
	}
}

包含关系的资源集合

use alsvanzelf\jsonapi\CollectionDocument;
use alsvanzelf\jsonapi\objects\ResourceObject;

$arthur      = new ResourceObject('user', 1);
$ford        = new ResourceObject('user', 2);
$zaphod      = new ResourceObject('user', 42);
$heartOfGold = new ResourceObject('starship', 2001);

$arthur->add('name', 'Arthur Dent');
$ford->add('name', 'Ford Prefect');
$zaphod->add('name', 'Zaphod Beeblebrox');
$heartOfGold->add('name', 'Heart of Gold');

$zaphod->addRelationship('drives', $heartOfGold);

$users    = [$arthur, $ford, $zaphod];
$document = CollectionDocument::fromResources(...$users);
$document->sendResponse();

这将导致

{
	"jsonapi": {
		"version": "1.1"
	},
	"data": [
		{
			"type": "user",
			"id": "1",
			"attributes": {
				"name": "Arthur Dent"
			}
		},
		{
			"type": "user",
			"id": "2",
			"attributes": {
				"name": "Ford Prefect"
			}
		},
		{
			"type": "user",
			"id": "42",
			"attributes": {
				"name": "Zaphod Beeblebrox"
			},
			"relationships": {
				"drives": {
					"data": {
						"type": "starship",
						"id": "2001"
					}
				}
			}
		}
	],
	"included": [
		{
			"type": "starship",
			"id": "2001",
			"attributes": {
				"name": "Heart of Gold"
			}
		}
	]
}

将异常转换为jsonapi

use alsvanzelf\jsonapi\ErrorsDocument;

$exception = new Exception('That is not valid', 422);

$document = ErrorsDocument::fromException($exception);
$document->sendResponse();

这将导致

{
	"jsonapi": {
		"version": "1.1"
	},
	"errors": [
		{
			"status": "422",
			"code": "Exception",
			"meta": {
				"class": "Exception",
				"message": "That is not valid",
				"code": 422,
				"file": "README.md",
				"line": 137,
				"trace": []
			}
		}
	]
}

这在开发中可能很有用。对于生产使用，您最好构建一个只包含特定值的ErrorsDocument。

使用扩展和配置文件

打包了原子操作扩展和游标分页配置文件。任何第三方或自制的扩展都可以使用以下方法应用：

use alsvanzelf\jsonapi\ResourceDocument;
use alsvanzelf\jsonapi\interfaces\ExtensionInterface;

class ExampleExtension implements ExtensionInterface {
	public function getOfficialLink() {
		return 'https://example.org/extension-documentation';
	}
	
	public function getNamespace() {
		return 'foo';
	}
}

$document = new ResourceDocument('user', 42);
$document->add('name', 'Zaphod Beeblebrox');

$extension = new ExampleExtension();
$document->applyExtension($extension);
$document->addExtensionMember($extension, 'bar', 'baz');

$document->sendResponse();

这将导致

{
    "foo:bar": "baz",
    "jsonapi": {
        "version": "1.1",
        "ext": [
            "https://example.org/extension-documentation"
        ]
    },
    "data": {
        "type": "user",
        "id": "42",
        "attributes": {
            "name": "Zaphod Beeblebrox"
        }
    }
}

对于配置文件，可以使用类似的流程。

其他示例

所有类型响应的示例都在/examples目录中。

特性

此库支持JSON:API规范的1.1版本。

它支持生成和发送以下文档：

• 单个资源
• 资源集合
• 一对一和多对一关系
• 错误（轻松将异常转换为jsonapi输出）
• 1.1扩展和配置文件
• 1.1 @-members for JSON-LD和其他

此外，还有一些工具可以帮助处理传入的请求

• 解析请求选项（包括路径、稀疏字段集、排序字段、分页、过滤）
• 解析请求文档以创建、更新和删除资源及其关系

除了自定义扩展/配置文件外，还包含了以下官方扩展/配置文件：

• 原子操作扩展（示例代码，规范）
• 游标分页配置文件（示例代码，规范）

未来计划包括

• 验证请求选项（#58）
• 验证请求文档（#57）

贡献

如果您使用这个库，请通过创建问题提问或分享可以改进的地方。

欢迎提交bug问题或Pull Requests！

许可证

MIT