README

仓库弃用日期：2019-12-31

该仓库已迁移至laminas-api-tools/api-tools-versioning。

简介

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

要求

请参阅composer.json文件。

安装

运行以下composer命令

$ composer require zfcampus/zf-versioning

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

"require": {
    "zfcampus/zf-versioning": "^1.2"
}

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

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

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

zf-component-installer

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

配置

用户配置

此模块用户配置的最高级配置键为zf-versioning。

键：content-type

content-type键用于指定用于解析基于媒体类型的版本控制信息的正则表达式数组。实现中提供了一个默认的正则表达式，这也可以作为创建更具体解析的正则表达式的示例。

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

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

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

所有捕获的部分应使用命名参数。一个更具体的例子，顶层键可能看起来像

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

键：default_version

default_version键提供了在没有客户端提供版本的情况下使用的默认版本号。default_version的默认值为1。

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

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

完整示例

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

或

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

键：uri

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

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

示例

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

系统配置

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

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

ZF2事件

zf-versioning不提供新事件，但提供了4个不同的监听器

ZF\Versioning\PrototypeRouteListener

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

ZF\Versioning\VersionListener

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

ZF\Versioning\AcceptListener

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

ZF\Versioning\ContentTypeListener

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

ZF2服务

zf-versioning除了提供事件监听器之外，不提供其他独特服务，即

• ZF\Versioning\VersionListener
• ZF\Versioning\AcceptListener
• ZF\Versioning\ContentTypeListener