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键提供了在客户端未提供版本的情况下使用的默认版本号。default_version的默认值是1。

该设置接受以下两种可能的值之一

• 一个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