README

Collection+JSON 媒体类型的 PHP 实现

规范

http://amundsen.com/media-types/collection/

安装

CollectionJson 需要 php >= 7.0

使用 Composer 安装 CollectionJson

{
    "require": {
        "mvieira/collection-json": "dev-master"
    }
}

或

$ composer require mvieira/collection-json

贡献

请参阅 CONTRIBUTING 获取详细信息。

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

文档

创建集合

$collection = (new Collection())
    ->withItem((new Item('https://example.co/item/1'))
        ->withDataSet([
            new Data('data 1'),
            new Data('data 2', 'value 2')
        ])
        ->withLink(
            new Link('https://example.co/item/1', Relation::ITEM)
        )
    );

print json_encode($collection);

{
    "collection": {
        "version": "1.0",
        "items": [
            {
                "data": [
                    {
                        "name": "data 1",
                        "value": null
                    },
                    {
                        "name": "data 2",
                        "value": "value 2"
                    }
                ],
                "href": "http:\/\/example.com\/item\/1",
                "links": [
                    {
                        "href": "https:\/\/example.co\/item\/1",
                        "rel": "item",
                        "render": "link"
                    }
                ]
            }
        ]
    }
}

创建实体

所有实体 Collection、Data、Error、Item、Link、Query、Template 都可以通过使用静态方法 fromArray 创建...

$data = Data::fromArray([
    'name' => 'email',
    'value' => 'hello@example.co'
]);

...或通过使用访问器（注意实体是不可变的）...

$data = (new Data('email'))
    ->withValue('hello@example.co');

...或通过构造函数...

$data = new Data('email', 'hello@example.co');

打印数据

注意：除了数据的价值属性，它允许有 NULL 值（参见规范），所有 NULL 属性和空数组都将从 JSON 和数组表示中排除。

打印 JSON 表示

所有实体实现了 JsonSerializable 接口，因此您可以在任何时候调用 json_encode() 方法。

print json_encode($collection);

{
    "collection": {
        "version": "1.0",
        "items": [
            ...
        ],
        "links": [
            ...
        ]
    }
}

打印数组表示

所有实体实现了一个名为 ArrayConvertible 的自定义接口，因此您可以在任何时候调用 toArray() 方法。此方法将递归地调用所有嵌套实体的方法。

print_r($collection->toArray());

Array
(
    [collection] => Array
        (
            [version] => 1.0
            [items] => Array
                ...

            [links] => Array
                ...

        )

)

包装

CollectionJson\Entity\Collection 实体将被包装...

echo json_encode($collection);

{
    "collection": {
        "version": "1.0"
     }
}

...然而其他实体在转换为 JSON 或数组时不会包装。

$template = new Template();
echo json_encode($template);

{
    "data": [
        ...
    ]
}

但是，您可以调用 wrap() 方法来包装 JSON 或数组表示。

$template->wrap();
echo json_encode($template);

{
    "template": {
        "data": [
            ...
        ]
    }
}

示例

示例位于 ./examples/ 目录中，您可以在命令行中通过运行以下命令执行它们：

$ make examples

或分别执行

$ php ./examples/client-collection.php

处理数据和链接

为了使用 CollectionJson 数组中的数据和链接，API 提供了两个实现类似逻辑的接口。

Item、Query 和 Template 实体实现的 DataAware 接口提供了 withData、withoutData、withDataSet、getDataSet、getFirstData 和 getLastData 方法。
Collection 和 Item 实体实现的 LinkAware 接口提供了 withLink、withoutLink、withLinkSet、getLinks、getFirstLink 和 getLastLink 方法。

它们允许您向实现它们的对象添加相应的实体。

// this...
$item = (new Item('https://example.co/item/1'))
    ->withData([
        'name' => 'email',
        'value' => 'email value'
    ]);

// ...is similar to
$data = Data::fromArray([
    'name' => 'email',
    'value' => 'email value'
]);

$item = (new Item('https://example.co/item/1'))
    ->withData($data);

// and that...
$item = (new Item('https://example.co/item/1'))
    ->withDataSet([
        new Data('email', 'hello@example.co'),
        new Data('tel', '0000000000')
    ]);

// ...is similar to
$data1 = Data::fromArray([
    'name' => 'email',
    'value' => 'hello@example.co'
]);
$data2 = Data::fromArray([
    'name' => 'tel',
    'value' => '0000000000'
]);
$item = (new Item('https://example.co/item/1'))
    ->withDataSet([
        $data1,
        $data2
    ]);

验证

现在可以使用 Symfony 验证器通过验证进入您 API 的数据。

use CollectionJson\Validator\Dataset as DatasetValidator;
use Symfony\Component\Validator\Constraints;

$constraints = [
    'id' => [
        new Constraints\NotBlank(),
    ],
    'url' => [
        new Constraints\NotBlank(),
        new Constraints\Url(),
    ],
    'email' => [
        new Constraints\NotBlank(),
        new Constraints\Email(),
    ],
];

$template = (new Template())
    ->withData(new Data('id', '123'))
    ->withData(new Data('url', 'http://example.co'))
    ->withData(new Data('email', 'test@example.co'));

$errors = (new DatasetValidator())
    ->validate($template->getDataSet(), $constraints);

它将返回错误列表。

mvieira / collection-json

维护者

详细信息