README

HATEOAS 兼容的 Restful 资源描述，包含将资源以 json 或 xml 格式表示的格式化工具。

安装

使用 composer require stratadox/rest-resource 安装

示例（json）

格式化为 json 输出的资源

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\DefaultJsonFormatter;
use Stratadox\RestResource\Link;
use Stratadox\RestResource\Links;
use Stratadox\RestResource\Type;

$json = DefaultJsonFormatter::fromBaseUri('https://a.server.somewhere/');

$resource = new BasicResource(
    'hateoas-resource',
    ['foo' => 'bar'],
    Links::provide(
        Link::to('foo/1', Type::get('Foo'))
    )
);

$this->assertJsonStringEqualsJsonString(
    '{
        "hateoas-resource": {
            "foo": "bar",
            "links": [
                {
                    "href": "server\/foo\/1",
                    "rel": "Foo",
                    "type": "GET"
                }
            ]
        }
    }',
    $json->from($resource)
);

示例（xml）

相同的资源，现在格式化为 xml 输出

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\DefaultXmlFormatter;
use Stratadox\RestResource\Link;
use Stratadox\RestResource\Links;
use Stratadox\RestResource\Type;

$xml = DefaultXmlFormatter::fromBaseUri('https://a.server.somewhere/');

$resource = new BasicResource(
    'hateoas-resource',
    ['foo' => 'bar'],
    Links::provide(
        Link::to('foo/1', Type::get('Foo'))
    )
);

$this->assertXmlStringEqualsXmlString(
    '<?xml version="1.0"?>
    <hateoas-resource>
      <foo>bar</foo>
      <links>
        <link>
          <href>server/foo/1</href>
          <rel>Foo</rel>
          <type>GET</type>
        </link>
      </links>
    </hateoas-resource>',
    $xml->from($resource)
);

示例（紧凑的 xml）

相同的资源再次，现在格式化为 xml，更简洁

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\CondensedXmlFormatter;
use Stratadox\RestResource\Link;
use Stratadox\RestResource\Links;
use Stratadox\RestResource\Type;

$xml = CondensedXmlFormatter::fromBaseUri('https://a.server.somewhere/');

$resource = new BasicResource(
    'hateoas-resource',
    ['foo' => 'bar'],
    Links::provide(
        Link::to('foo/1', Type::get('Foo'))
    )
);

$this->assertXmlStringEqualsXmlString(
    '<?xml version="1.0"?>
    <hateoas-resource foo="bar">
      <links>
        <link href="server/foo/1" rel="Foo" type="GET" />
      </links>
    </hateoas-resource>',
    $xml->from($resource)
);

单数化

基于数组结构格式化 xml 文档比转换为 json 略为复杂。

例如，给定输入

[
    'people' => [
        [
            'id' => 1,
            'name' => 'Alice',
        ],
        [
            'id' => 2,
            'name' => 'Bob',
        ],
    ]
];

在 json 中，可能会得到这样的输出

{
  "people": [
    {
      "id": 1,
      "name": "Alice"
    },
    {
      "id": 2,
      "name": "Bob"
    }
  ]
}

然而，我们期望 xml 会有类似这样的输出

<people>
    <person>
        <id>1</id>
        <name>Alice</name>
    </person>
    <person>
        <id>2</id>
        <name>Bob</name>
    </person>
</people>

或者

<people>
    <person id="1" name="Alice" />
    <person id="2" name="Bob" />
</people>

默认情况下，xml 格式化器使用 inflection 将复数转换为单数版本。因此，上述 PHP 数组结构确实会生成预期的 xml。任何 inflector 支持的语言都可以使用，例如

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\DefaultXmlFormatter;
use Stratadox\RestResource\Links;

$xml = DefaultXmlFormatter::in('fr', '/');

$resource = new BasicResource(
    'resource-travaux',
    ['travaux' => ['foo', 'bar', 'baz']],
    Links::none()
);

$this->assertXmlStringEqualsXmlString(
    '<?xml version="1.0"?>
    <resource-travaux>
        <travaux>
            <travail>foo</travail>
            <travail>bar</travail>
            <travail>baz</travail>
        </travaux>
    </resource-travaux>',
    $xml->from($resource)
);

可以使用任何单数化器。如果您不想冒使用无法转换为单数版本的风险，基本单数化器可能是一个选择，尽管它会生成类似以下示例的 xml

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\BasicSingularizer;
use Stratadox\RestResource\DefaultXmlFormatter;
use Stratadox\RestResource\Links;

$xml = DefaultXmlFormatter::withSingularizer('/', new BasicSingularizer());

$resource = new BasicResource(
    'people-resource',
    ['people' => [
        ['id' => 1, 'name' => 'Alice'],
        ['id' => 2, 'name' => 'Bob'],
    ]],
    Links::none()
);

$this->assertXmlStringEqualsXmlString(
    '<?xml version="1.0"?>
    <people-resource>
        <people>
            <item>
                <id>1</id>
                <name>Alice</name>
            </item>
            <item>
                <id>2</id>
                <name>Bob</name>
            </item>
        </people>
    </people-resource>',
    $xml->from($resource)
);

或者，更简洁一些

<?php

use Stratadox\RestResource\BasicResource;
use Stratadox\RestResource\BasicSingularizer;
use Stratadox\RestResource\CondensedXmlFormatter;
use Stratadox\RestResource\Links;

$xml = CondensedXmlFormatter::withSingularizer('/', new BasicSingularizer());

$resource = new BasicResource(
    'people-resource',
    ['people' => [
        ['id' => 1, 'name' => 'Alice'],
        ['id' => 2, 'name' => 'Bob'],
    ]],
    Links::none()
);

$this->assertXmlStringEqualsXmlString(
    '<?xml version="1.0"?>
    <people-resource>
        <people>
            <item id="1" name="Alice" />
            <item id="2" name="Bob" />
        </people>
    </people-resource>',
    $xml->from($resource)
);