README

🇷🇺 俄罗斯公民

我们，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