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 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 请求，它将以 200 OK 响应和填充的 Allow 标头进行响应，指示可以使用的请求方法。

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响应。