README

🇷🇺 俄罗斯公民

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

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

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

🇺🇸 致俄罗斯公民

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

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

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

简介

api-tools-versioning 是一个 Laminas 模块，通过 URI 和 Accept 或 Content-Type 媒体类型头实现服务版本控制的自动化。从 URI 或头媒体类型提取的与版本控制相关的信息将在路由匹配对象中提供。在控制器服务名称使用与正则表达式 V(\d) 匹配的子命名空间的情况下，匹配的控制器服务名称将更新为当前匹配的版本字符串。

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

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

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

"require": {
    "laminas-api-tools/api-tools-versioning": "^1.2"
}

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

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

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

laminas-component-installer

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

配置

用户配置

此模块用户配置的最高级配置键是 api-tools-versioning。

键：content-type

《content-type》键用于指定一个正则表达式数组，这些表达式将用于解析基于媒体类型的版本信息中的Content-Type和Accept头。实现中提供了一个默认的正则表达式，它还应作为创建更具体解析的正则表达式的示例。

'#^application/vnd\.(?P<laminas_ver_vendor>[^.]+)\.v(?P<laminas_ver_version>\d+)\.(?P<laminas_ver_resource>[a-zA-Z0-9_-]+)$#'

此规则将匹配以下伪代码路由

application/vnd.{api name}.v{version}(.{resource})?+json

所有捕获的部分应使用命名参数。一个更具体的例子，顶级键将如下所示

'api-tools-versioning' => [
    'content-type' => [
        '#^application/vendor\.(?P<vendor>mwop)\.v(?P<version>\d+)\.(?P<resource>status|user)$#',
    ],
],

键：default_version

default_version键提供默认版本号，在客户端未提供版本号的情况下使用。1是default_version的默认值。

设置接受以下两个可能值之一

• PHP integer，表示所有路由的默认版本号。
• 一个关联数组，其中键是路由名称，值是与相关路由一起使用的默认版本。

完整示例

// Set v2 as default version for all routes
'api-tools-versioning' => [
    'default_version' => 2,
],

或

// Set default version to v2 and v3 for the users and status routes respectively
'api-tools-versioning' => [
    'default_version' => [
        'myapi.rest.users' => 2,
        'myapi.rpc.status' => 3,
    ],
],

键：uri

uri键负责识别需要添加路由匹配信息以进行基于URL的版本化的路由。此键是用于Laminas router.routes配置的路由名称数组。如果特定路由是子路由，则链式操作将发生在最顶层的祖先路由。

路由匹配段由[/v:version]规则组成，同时指定版本参数仅允许数字。

示例

'api-tools-versioning' => [
    'uri' => [
        'api',
        'status',
        'user',
    ],
],

系统配置

以下配置在config/module.config.php中提供，以启用模块的功能

'service_manager' => [
    'factories' => [
        \Laminas\ApiTools\Versioning\AcceptListener::class => \Laminas\ApiTools\Versioning\Factory\AcceptListenerFactory::class,
        \Laminas\ApiTools\Versioning\ContentTypeListener::class => \Laminas\ApiTools\Versioning\Factory\ContentTypeListenerFactory::class,
        \Laminas\ApiTools\Versioning\VersionListener::class => \Laminas\ServiceManager\Factory\InvokableFactory::class,
    ],
],

Laminas事件

api-tools-versioning没有提供新的事件，但提供了4个不同的监听器

Laminas\ApiTools\Versioning\PrototypeRouteListener

此监听器连接到ModuleEvent::EVENT_MERGE_CONFIG。它负责迭代在api-tools-versioning.uri配置中提供的路由，以查找在router.routes配置中对应的路由。当检测到匹配项时，此监听器将版本化路由匹配配置应用于路由配置。

Laminas\ApiTools\Versioning\VersionListener

此监听器连接到MvcEvent::EVENT_ROUTE，优先级为-41。此监听器负责更新使用版本化命名空间命名方案的控制器服务名称。例如，如果当前匹配的路由提供的控制器名称为Foo\V1\Bar，并且当前通过URL或媒体类型选择的版本为4，则控制器服务名称将更新为Foo\V4\Bar；

Laminas\ApiTools\Versioning\AcceptListener

此监听器连接到MvcEvent::EVENT_ROUTE，优先级为-40。此监听器负责从请求中存在的任何Accept头中解析提供的信息（有关详细信息，请参阅content-type配置键），并将该信息分配给路由匹配项，其中正则表达式参数名称作为键。

Laminas\ApiTools\Versioning\ContentTypeListener

此监听器连接到MvcEvent::EVENT_ROUTE，优先级为-40。此监听器负责从请求中存在的任何Content-Type头中解析提供的信息（有关详细信息，请参阅content-type配置键），并将该信息分配给路由匹配项，其中正则表达式参数名称作为键。

Laminas服务

api-tools-versioning除了为事件监听器提供服务之外，没有提供独特的服务

• Laminas\ApiTools\Versioning\VersionListener
• Laminas\ApiTools\Versioning\AcceptListener
• Laminas\ApiTools\Versioning\ContentTypeListener