nuXnik/collection-plus-json

轻量级PHP库，用于操作Collection+JSON超媒体类型对象。可作为服务器或客户端使用

维护者

详细信息

github.com/nuxnik/collection-json-php

主页

源代码

安装: 10,948

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 1

1.1.0 2021-01-12 14:04 UTC

Requires

Requires (Dev)

MIT a48c45f56bdd1d1f1946484b7f1ca7b698d60fd8

phpjsonrestapilibraryhypermediasoacollectionrestapicollection-jsonjsonapicollection-json-php

This package is auto-updated.

Last update: 2024-09-29 05:28:33 UTC

README

版本：1.0.0

简介

Collection+JSON 是一种基于JSON的读写超媒体类型，旨在支持简单集合的管理和查询。

Collection+JSON 超媒体类型旨在支持简单列表（联系人、任务、博客条目等）的完整读写功能。该媒体类型支持的标准应用语义包括创建、读取、更新和删除（CRUD），以及支持预定义查询，包括查询模板（类似于HTML "GET" 表单）。写操作定义使用服务器作为响应表示的一部分提供的模板对象。

来源于 Collection+JSON 网站

## 安装

  1. 安装 composer.phar（如果您还没有安装的话）

  2. 编辑您的 composer.json 文件以包含库

       "require": {
          "other/libraries" : "..."
          "nuxnik/collection-plus-json": "*"
   }

  3. 检查是否一切正常

       require '../vendor/autoload.php';

   $test = new \CollectionPlusJson\Collection('http://api.test.io');
   echo json_encode($test->output());

    该代码应该输出

       {"collection":
      {"version":"1.0.0",
       "href":"http:\/\/api.test.io"
       }
   }

示例

//Build the collection object
$colors = new Collection('http://api.colors.io/');

//Add a Link to the collection object
$colors->addLink(new Link($colors->getHref()->extend('rss'), 'feed', 'rss-feed', '', 'Subscribe to our RSS feed!'));

//Build an item
$color1 = new Item($colors->getHref()->extend('1'));
$color1->addData('id', '1', 'This is the color id.')
       ->addData('hexValue', '#9932CC', 'This is the color in hex format.');

// or add data with dynamic setter
$color1->sethumanValue('DarkOrchid', 'This is the color in human readable format.');

$color1->addLink(new Link('https://w3schools.org.cn/tags/ref_colornames.asp', 'source'));
$color1->addLink(new Link('https://w3schools.org.cn/tags/ref_color_tryit.asp?hex=9932CC', 'colorTest'));

//Build a second item
$color2 = new Item($colors->getHref()->extend('2'));
$color2->addData('id', '2', 'This is the color id.')
       ->addData('hexValue', '#FFFFF0', 'This is the color in hex format.');

// or add data with dynamic setter
$color2->sethumanValue('DarkOrchid', 'This is the color in human readable format.');

$color2->addLink(new Link('https://w3schools.org.cn/tags/ref_colornames.asp', 'source'));
$color2->addLink(new Link('https://w3schools.org.cn/tags/ref_color_tryit.asp?hex=FFFFF0', 'colorTest'));

//Add both items
$colors->addItems([$color1, $color2]);

//Build a collection query
$query = new Query($colors->getHref()->extend('search'), 'search');
$query->addData('search');
$colors->addQuery($query);

//Set the collection template
$template = new Template();
$template->addData('id', 'This is the color id.')
         ->addData('hexValue', 'This is the color in hex format.')
         ->addData('humanValue', 'This is the color in human readable format.')
         ->addData('colorTest', 'Link to test how your color looks with other colors.');

// or add data with dynamic setter
$template->setSource('Link to colors source');

$colors->setTemplate($template);

//Set an error
$error = new Error('error-test', 'ABC123', 'This is a test error. Server has encountered a problem and could not process your request, please try later.');
$colors->setError($error);

//Send response
$app->response->headers->set('Content-Type', 'application/vnd.collection+json');
echo json_encode($colors->output());

/*
Output would be:

{
    "collection": {
        "version": "1.0.1",
        "href": "http://api.colors.io/",
        "links": [
            {
                "href": "http://api.colors.io/rss",
                "rel": "feed",
                "prompt": "Subscribe to our RSS feed!",
                "name": "rss-feed",
            }
        ],
        "items": [
            {
                "href": "http://api.colors.io/1",
                "data": [
                    {
                        "name": "id",
                        "value": "1",
                        "prompt": "This is the color id."
                    },
                    {
                        "name": "hexValue",
                        "value": "#9932CC",
                        "prompt": "This is the color in hex format."
                    },
                    {
                        "name": "humanValue",
                        "value": "DarkOrchid",
                        "prompt": "This is the color in human readable format."
                    }
                ],
                "links": [
                    {
                        "href": "https://w3schools.org.cn/tags/ref_colornames.asp",
                        "rel": "source",
                    },
                    {
                        "href": "https://w3schools.org.cn/tags/ref_color_tryit.asp?hex=9932CC",
                        "rel": "colorTest",
                    }
                ]
            },
            {
                "href": "http://api.colors.io/2",
                "data": [
                    {
                        "name": "id",
                        "value": "2",
                        "prompt": "This is the color id."
                    },
                    {
                        "name": "hexValue",
                        "value": "#FFFFF0",
                        "prompt": "This is the color in hex format."
                    },
                    {
                        "name": "humanValue",
                        "value": "Ivory",
                        "prompt": "This is the color in human readable format."
                    }
                ],
                "links": [
                    {
                        "href": "https://w3schools.org.cn/tags/ref_colornames.asp",
                        "rel": "source",
                    },
                    {
                        "href": "http://w3schools.org.cn/tags/ref_color_tryit.asp?hex=FFFFF0",
                        "rel": "colorTest",
                    }
                ]
            }
        ],
        "queries": [
            {
                "href": "http://api.colors.io/search",
                "rel": "search",
                "data": [
                    {
                        "name": "search",
                        "value": null,
                        "prompt": ""
                    }
                ]
            }
        ],
        "template": [
            {
                "name": "id",
                "value": "",
                "prompt": "This is the color id."
            },
            {
                "name": "hexValue",
                "value": "",
                "prompt": "This is the color in hex format."
            },
            {
                "name": "humanValue",
                "value": "",
                "prompt": "This is the color in human readable format."
            },
            {
                "name": "source",
                "value": "",
                "prompt": "Link to colors source."
            },
            {
                "name": "colorTest",
                "value": "",
                "prompt": "Link to test how your color looks with other colors."
            }
        ],
        "error": {
            "title": "error-test",
            "code": "ABC-123",
            "message": "This is a test error. Server has encountered a problem and could not process your request, please try later."
        }
    }
}

消费一个 Collection+JSON 对象

此功能使Collection+JSON格式的普通JSON字符串可以被消费并转换为Collection对象，以便轻松操作。

带有传输对象的示例

// init Collection object with json string to parse
$collection = new Collection(json_decode($collectionJson, true));

// get the first item
$item = $collection->getFirstItem();

// get a fake transfer object
$entity = new ExampleEntity();

// add the data with dynamic getters from item object
$entity->setFoo($item->getFoo());
$entity->setBar($item->getBar());

// save to example database
$repo->persist($entity);
$repo->flush();

带有来自POST/PUT请求的模板对象的示例。有关详细信息，请参阅 Collection+JSON 文档

// init Template object with json string to parse
$template = new Template(json_decode($collectionJsonTemplate, true));

// get a fake transfer object
$entity = new ExampleEntity();

// add the data with dynamic getters from template object
$entity->setFoo($template->getFoo());
$entity->setBar($template->getBar());

// save to example database
$repo->persist($entity);
$repo->flush();

创建一个客户端以与Collection+JSON服务器通信

获取所有数据

// init the http client and collection class
$href = 'http://api.colors.io';
$client = new GuzzleClient(['base_uri' => $href]);
$collection = new \CollectionPlusJson\Collection( $href, $client );

// get data from endpoint
$collection = $collection->get();

// iterate through the items
$items = $collection->getItems();
foreach( $items as $item) {
   echo $item->getId() . "\n";
}

如果JSON对象与上面的相同，则以下将输出

1
2

获取单个项目并更新它

// init the http client and collection class
$href = 'http://api.colors.io';
$client = new GuzzleClient(['base_uri' => $href]);
$collection = new \CollectionPlusJson\Collection( $href, $client );

// get data from endpoint
$collection = $collection->get('/color2');

// show the hex value
$item = $collection->getFirstItem();
echo $item->getHexValue() . "\n";

// update the color
$item->setHexValue('#FF0000');
$item->setHumanValue('red');

// import the item to the collection template
$collection->getTemplate()->importItem($item);

// put/save to server
$collection = $collection->put();

// show the hex value
$item = $collection->getFirstItem();
echo $item->getHexValue() . "\n";

如果JSON对象与上面的相同，则以下将输出

#FFFFF0
#FF0000

创建和删除单个项目

// init the http client and collection class
$href = 'http://api.colors.io';
$client = new GuzzleClient(['base_uri' => $href]);
$collection = new \CollectionPlusJson\Collection( $href, $client );

// get data from endpoint
$collection = $collection->get();

// enter values into the template
$tpl = $collection->getTemplate();
$tpl->setHexValue('#00FF00');
$tpl->setHumanValue('green');

// post/save to server
$collection = $collection->post();

// show the hex value
$item = $collection->getFirstItem();
echo $item->getHexValue() . "\n";

// delete the item
$item->delete();

如果JSON对象与上面的相同，则以下将输出

#00FF00

爬取/跟随链接

// init the http client and collection class
$href = 'http://api.colors.io';
$client = new GuzzleClient(['base_uri' => $href]);
$collection = new \CollectionPlusJson\Collection( $href, $client );

// get data from endpoint
$item = $collection->get()->getFirstItem()
$collection = $item->follow();

echo  $collection->getFirstItem()->getHumanValue();

如果JSON对象与上面的相同，则以下将输出

DarkOrchid