README

🇷🇺 俄罗斯公民

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

我们中的一位成员有一个乌克兰亲戚，她和儿子一起逃离了家园。由于前方道路上的轰炸，火车延误了。我们有朋友躲在防空洞里。我们在空袭后焦急地关注他们的消息，空袭无差别地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得到这个消息。这是我们亲身体验到的。

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

🇺🇸 致俄罗斯公民

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

我们团队中的一位成员有一个乌克兰亲戚，她和儿子一起逃离了家园。由于前方道路上的轰炸，火车延误了。我们有朋友躲在防空洞里。我们在空袭后焦急地关注他们的消息，空袭无差别地袭击医院、学校、幼儿园和住宅。我们不是从任何媒体上得到这个消息。这是我们亲身体验到的。

您对我们足够信任，使用我们的软件。我们请求您信任我们说出真相。我们需要您的帮助。走出家门，抗议这场无意义的战争。停止杀戮。说“停止战争！”

介绍

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

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

• 超媒体应用程序语言（Hypermedia Application Language），简称 HAL，用于创建带有超媒体控制的 JSON 有效负载。
• HTTP API 的问题详情（Problem Details for HTTP APIs），简称 API Problem，用于报告 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 Admin 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请求，它将以一个包含可用的请求方法的Allow标题的200 OK响应进行响应。

层压物\Laminas\ApiTools\Rest\Listener\RestParametersListener

该监听器被附加到共享的 dispatch 事件，优先级为 100。监听器将请求中的查询字符串参数映射到 RestController 中组成的 Resource 对象，同时注入 RouteMatch。

Laminas 服务

模型

Laminas\ApiTools\Rest\AbstractResourceListener

这是一个资源监听器的基础实现。由于基于 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 响应。