README

🇷🇺 俄罗斯公民

我们是 Laminas 的参与者，来自不同的国家。我们中许多人都有俄罗斯和乌克兰的朋友、亲戚和同事。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些祖父母在第二次世界大战中与法西斯作战。在这里，没有人支持法西斯主义。

我们中的一员有一个乌克兰亲戚，她和她儿子一起从家中逃出。由于前方道路上的轰炸，火车延误了。我们有朋友躲在防空洞里。在空袭之后，我们焦急地等待他们的消息，空袭不分青红皂白地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得知的。我们直接目睹了这一切。

您足够信任我们使用我们的程序，我们请求您再次信任我们。我们需要帮助。走出家门，抗议这场毫无意义的战争。停止杀戮。说“停止战争！”

🇺🇸 致俄罗斯公民

我们 Laminas 的成员来自世界各地。我们中许多人都有俄罗斯和乌克兰的朋友、家人和同事。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些祖父母在第二次世界大战中与纳粹作战。在这里，没有人支持法西斯主义。

我们团队的一员有一个乌克兰亲戚，她和她儿子一起逃离了家园。由于前方道路上的轰炸，火车延误了。我们有朋友躲在防空洞里。在空袭之后，我们焦急地等待他们的消息，空袭不分青红皂白地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得知的。这是我们亲身经历的事情。

您足够信任我们使用我们的软件。我们请求您在我们谈论这个问题时信任我们。我们需要您的帮助。走出家门，抗议这场不必要的战争。停止杀戮。说“停止战争！”

简介

本模块提供结构和代码，以便快速实现使用 JSON 作为传输的 RESTful API。

它允许您创建以下标准的 RESTful JSON API

• 超媒体应用语言，简称 HAL，用于创建带有超媒体控制的 JSON 有效负载。
• HTTP API 的问题细节，简称 API 问题，用于报告 API 问题。

要求

请参阅composer.json 文件。

安装

运行以下 composer 命令

$ composer require laminas-api-tools/api-tools-rest

或者，手动将以下内容添加到您的 composer.json 中的 require 部分

"require": {
    "laminas-api-tools/api-tools-rest": "^1.3"
}

然后运行 composer update 以确保安装了模块。

最后，将模块名称添加到项目 config/application.config.php 中的 modules 键下

return [
    /* ... */
    'modules' => [
        /* ... */
        'Laminas\ApiTools\Rest',
    ],
    /* ... */
];

laminas-component-installer

如果您使用 laminas-component-installer，该插件会为您将 api-tools-rest 作为模块安装。

配置

用户配置

配置此模块使用的顶级键是 api-tools-rest。

键：控制器服务名称

api-tools-rest 下的每个键都是控制器服务名称，其值是一个包含以下一个或多个键的数组。

子键：collection_http_methods

在向集合发送请求时允许的 HTTP 方法数组。

子键：entity_http_methods

在请求实体时允许的 HTTP 方法数组。

子键：collection_name

表示中嵌入属性的名称，表示集合。

子键：collection_query_whitelist（可选）

要为集合请求和生成集合链接而白名单的查询字符串参数数组。这些参数将被传递到资源类的 fetchAll() 方法。请求中存在的任何这些参数也将用于生成集合链接。

您可能希望白名单的查询字符串参数示例包括 "sort"，"filter" 等。

从 1.5.0 版本开始：如果存在针对 GET HTTP 方法的输入过滤器，其键将与配置中的键合并。

子键：controller_class（可选）

用于创建控制器服务的替代控制器类；它 必须 扩展 Laminas\ApiTools\Rest\RestController。只有当您正在更改 RestController 中现有的工作流程时，才使用此功能。

子键：identifier（可选）

控制器的事件标识符名称。它允许多个控制器实例对不同的共享事件集做出反应。

子键：resource_identifiers（可选）

资源的事件标识符名称或名称数组。

子键：entity_class

用于表示实体的类。主要用于内省（例如在 Laminas API Tools 管理UI中）。

子键：route_name

与该 REST 服务关联的路由名称。当需要在响应中生成链接时，将使用此名称。

子键：route_identifier_name

路由规范中标识符的参数名称。

子键：listener

将调度到处理任何集合或实体请求的资源类。

子键：page_size

每页集合中返回的实体数量。仅在返回的集合是 Laminas\Paginator\Paginator 实例或其派生类时使用。

子键：max_page_size（可选）

每页集合中返回的实体数量的最大值。这与 page_size_param 进行测试。此参数可以设置为帮助防止针对您的 API 的拒绝服务攻击。

子键：min_page_size（可选）

每页集合中返回的实体数量的最小值。这与 page_size_param 进行测试。

子键：page_size_param（可选）

用于设置每个请求页面大小的查询字符串参数名称。默认情况下不设置；我们建议您有额外的逻辑来确保页面大小的上限，以防止针对您的 API 的拒绝服务攻击。

用户配置示例

'AddressBook\\V1\\Rest\\Contact\\Controller' => [
    'listener' => 'AddressBook\\V1\\Rest\\Contact\\ContactResource',
    'route_name' => 'address-book.rest.contact',
    'route_identifier_name' => 'contact_id',
    'collection_name' => 'contact',
    'entity_http_methods' => [
        0 => 'GET',
        1 => 'PATCH',
        2 => 'PUT',
        3 => 'DELETE',
    ],
    'collection_http_methods' => [
        0 => 'GET',
        1 => 'POST',
    ],
    'collection_query_whitelist' => [],
    'page_size' => 25,
    'page_size_param' => null,
    'entity_class' => 'AddressBook\\V1\\Rest\\Contact\\ContactEntity',
    'collection_class' => 'AddressBook\\V1\\Rest\\Contact\\ContactCollection',
    'service_name' => 'Contact',
],

系统配置

api-tools-rest 模块提供了以下配置，以确保其在 Laminas 框架应用程序中正确运行。

'service_manager' => [
    'invokables' => [
        'Laminas\ApiTools\Rest\RestParametersListener' => 'Laminas\ApiTools\Rest\Listener\RestParametersListener',
    ],
    'factories' => [
        'Laminas\ApiTools\Rest\OptionsListener' => 'Laminas\ApiTools\Rest\Factory\OptionsListenerFactory',
    ],
],

'controllers' => [
    'abstract_factories' => [
        'Laminas\ApiTools\Rest\Factory\RestControllerFactory',
    ],
],

'view_manager' => [
    // Enable this in your application configuration in order to get full
    // exception stack traces in your API-Problem responses.
    'display_exceptions' => false,
],

Laminas 事件

监听器

Laminas\ApiTools\Rest\Listener\OptionsListener

此监听器已注册到 MvcEvent::EVENT_ROUTE 事件，优先级为 -100。它有两个用途：

• 如果对一个它们不支持的方法的 REST 实体或集合发送请求，它将返回一个 405 Method not allowed 响应，并在 Allow 标头中包含可能使用的请求方法。
• 对于 OPTIONS 请求，它将以 200 OK 响应和一个包含可以使用的请求方法的 Allow 报头进行响应。

Laminas\ApiTools\Rest\Listener\RestParametersListener

此监听器连接到优先级为 100 的共享 dispatch 事件。监听器将请求中的查询字符串参数映射到在 RestController 中组成的 Resource 对象，以及注入 RouteMatch。

Laminas 服务

模型

Laminas\ApiTools\Rest\AbstractResourceListener

此抽象类是 Resource 监听器的基础实现。由于基于 api-tools-rest 的 REST 服务的分发是事件驱动的，因此必须构建一个监听器来监听从 Laminas\ApiTools\Rest\Resource（由 RestController 调用）触发的事件。以下方法在 dispatch() 期间被调用，具体取决于 HTTP 方法

• create($data) - 由对资源 集合 的 POST 请求触发。
• delete($id) - 由对资源 实体 的 DELETE 请求触发。
• deleteList($data) - 由对资源 集合 的 DELETE 请求触发。
• fetch($id) - 由对资源 实体 的 GET 请求触发。
• fetchAll($params = []) - 由对资源 集合 的 GET 请求触发。
• patch($id, $data) - 由对资源 实体 的 PATCH 请求触发。
• patchList($data) - 由对资源 集合 的 PATCH 请求触发。
• update($id, $data) - 由对资源 实体 的 PUT 请求触发。
• replaceList($data) - 由对资源 集合 的 PUT 请求触发。

Laminas\ApiTools\Rest\Resource

Resource 对象处理 REST 请求的业务逻辑分发。它组成一个 EventManager 实例，以便将操作委托给附加的监听器。此外，它组成请求信息，如 Request、RouteMatch 和 MvcEvent 对象，以便播种它创建并传递给监听器的 ResourceEvent。

控制器

Laminas\ApiTools\Rest\RestController

这是当控制器服务名称与配置的 REST 服务匹配时使用的基控制器实现。所有由 api-tools-rest 管理的 REST 服务都将使用此控制器（尽管是它单独的实例），除非它们指定了 controller_class 选项。实例通过 Laminas\ApiTools\Rest\Factory\RestControllerFactory 抽象工厂创建。

RestController 根据请求的 HTTP 方法调用 Laminas\ApiTools\Rest\Resource 中的相应方法。在成功时返回 HAL 负载数据，在错误时返回 API Problem 响应。