README

这是一个非常小巧但功能强大的Symfony2库，可以快速构建RESTful服务（特别是HTTP API）。此工具是一个库，而不是一个包。

安装

安装相对简单。需要三个步骤。首先，将正确的依赖项添加到您的 composer.json 文件中，并安装新库。

"brightmarch/rest-easy": "1.1.0"

您可以安全地假设master分支总是是最新的。

$ composer.phar install brightmarch/rest-easy

安装完成，现在您可以开始构建RESTful资源了。

使用

首先，您可能想要从自己的包开始。每个您想与该包一起工作的资源都必须扩展 Brightmarch\RestEasy\Controller\Controller 控制器。

示例控制器

<?php

namespace Sample\AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

use Brightmarch\RestEasy\Controller\Controller as RestController;

class AccountsController extends RestController
{

    public function indexAction()
    {
        // Describe what content types this resource supports.
        $this->resourceSupports('application/json', 'application/xml', 'text/html');

        $accounts = $this->get('doctrine')
            ->getManager()
            ->getRepository('SampleAppBundle:Account')
            ->findAll();

        // The type of the view will automatically
        // be found based on the Accept header.
        $parameters = [
            'accounts' => $accounts
        ];

        return $this->renderResource('SampleAppBundle:Accounts:accounts', $parameters);
    }

}

您必须描述此资源支持哪些内容类型。这意味着如果客户端发送一个客户端不接受的Accept头，则将返回一个406 Unacceptable响应。因为此资源支持三种内容类型，您必须有三个不同的视图：accounts.json.twig，accounts.xml.twig和accounts.html.twig。

此库不支持任何类型的序列化，并将渲染响应完全留给您。然而，我们建议您像实现HTML视图一样实现您的响应。通过将JSON或XML响应作为视图实现，您可以直接在视图中添加视图级逻辑（例如日期/区域格式化）。此外，通过使用视图作为响应，您能够在一个单独的文件中看到您的响应将是什么样子。

index.json.twig

{% autoescape false %}
[
    {% for account in accounts %}
        {
            "id": {{ account.getId|json_encode }},
            "name": {{ account.getName|json_encode }}
        }
    {% endfor %}
]
{% endautoescape %}

index.xml.twig

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
    {% for account in accounts %}
        <account>
            <id>{{ account.getId }}</id>
            <name>{{ account.getName }}</name>
        </account>
    {% endfor %}
</accounts>

index.html.twig

<!doctype html>
<html>
<head>
    <title>Accounts Resource</title>
</head>
<body>
    <ul>
        {% for account in accounts %}
            <li>{{ account.getName }}</li>
        {% endfor %}
    </ul>
</body>
</html>

一个稍微高级的控制器可能会找到一个实体并渲染它。您希望以请求的格式渲染它。您只需为这些格式创建模板。不要忘记如果需要，资源应相互链接。以下是一个Account的示例模板。

{% autoescape false %}
{
    "id": {{ account.getId }},
    "created_at": {{ account.getCreatedAt|format_date|json_encode }},
    "updated_at": {{ account.getUpdatedAt|format_date|json_encode }},
    "name": {{ account.getName|json_encode }},
    "identifier": {{ account.getIdentifier|json_encode }},
    "email": {{ account.getEmail|json_encode }},
    "lang": {{ account.getLang|json_encode }},
    "_links": [
        {
            "rel": "self",
            "url": {{ url('sample_app_view_account', { 'id': account.getId })|json_encode }}
        },
        {
            "rel": "alt",
            "url": {{ url('sample_app_view_account_identifier', { 'identifier': account.getIdentifier })|json_encode }}
        }
    ]
}
{% endautoescape %}

您会注意到有两个_links记录。一个直接指向它自己，另一个提供同一资源的替代URL。再次强调，通过像实现HTML视图一样构建JSON视图，您可以直接在视图中渲染您想要的任何数量的链接，而无需依赖复杂的序列化代码。

错误

此库支持正确处理HTTP错误。它包含几个用于处理错误的异常。包括

400: HttpBadSyntaxException
405: HttpMethodNotAllowedException
406: HttpNotAcceptableException
409: HttpConflictException
415: HttpUnsupportedMediaTypeException
510: HttpNotExtendedException
404: HttpNotFoundException
401: HttpUnauthorizedException

您负责捕获和渲染您的错误。您应该熟悉在Symfony中使用事件监听器来捕获内核异常，以自动将所有错误作为RESTful响应返回。一个简单的错误响应模板可能如下所示

{% autoescape false %}
{
    "httpCode": {{ httpCode }},
    "message": {{ message|json_encode }}
}
{% endautoescape %}

HTTP状态码也将作为响应有效负载的一部分发送回。例如，向上述资源发出此请求将导致406错误

$ curl -v -H "Accept: invalid/type" http://example.com/

< HTTP/1.1 406 Not Acceptable
< Content-Length: 195
< Content-Type: application/json; charset=utf-8
< 
{
    "httpCode": 406,
    "message": "This resource can not respond with a format the client will find acceptable. This resource supports: [application\/json, application\/xml, text\/html]."
}

如果无法确定异常的错误代码，则应使用默认的500错误代码。根据需要将添加更多HttpException类。如果您需要的状态码没有提供特定类，您可以使用根HttpException异常，并将状态码作为构造函数的第二个参数传递。

<?php

throw new HttpException("I am not a teapot.", 418);

JSON中间件

这个库采用可插拔的中间件架构，使用PHP Traits（称为Mixins）。您可以使用 HttpJsonMiddlewareMixin 混合来在响应中启用格式化的JSON。

要启用此中间件，只需在任意类中使用它即可。将重写 renderResource() 方法以格式化您的JSON响应（非JSON响应将保持不变）。

<?php

use Brightmarch\RestEasy\Controller\Mixin\HttpJsonMiddlewareMixin;

class AccountsController extends RestController
{

    use HttpJsonMiddlewareMixin;

    public function indexAction()
    {
        // ...

        return $this->renderResource('...');
    }

}

许可证

MIT许可证（MIT）

brightmarch / rest-easy

维护者

详细信息