PHPackages                             zfcampus/zf-versioning - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. zfcampus/zf-versioning

Abandoned → [laminas-api-tools/api-tools-versioning](/?search=laminas-api-tools%2Fapi-tools-versioning)ArchivedLibrary[HTTP & Networking](/categories/http)

zfcampus/zf-versioning
======================

ZF2 Module providing listeners and route prototypes for implementing API versioning

1.3.0(8y ago)131.9M—8.2%6[2 issues](https://github.com/zfcampus/zf-versioning/issues)3BSD-3-ClausePHPPHP ^5.6 || ^7.0

Since Oct 3Pushed 6y ago8 watchersCompare

[ Source](https://github.com/zfcampus/zf-versioning)[ Packagist](https://packagist.org/packages/zfcampus/zf-versioning)[ Docs](http://apigility.org/)[ RSS](/packages/zfcampus-zf-versioning/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (8)Versions (18)Used By (3)

ZF Versioning
=============

[](#zf-versioning)

> ## Repository abandoned 2019-12-31
>
> [](#repository-abandoned-2019-12-31)
>
> This repository has moved to [laminas-api-tools/api-tools-versioning](https://github.com/laminas-api-tools/api-tools-versioning).

[![Build Status](https://camo.githubusercontent.com/47daca4a4fa2cb3e8ca76092048ab29d18e83cbb45156a95a404f18618747d8b/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f7a6663616d7075732f7a662d76657273696f6e696e672e7376673f6272616e63683d6d6173746572)](https://secure.travis-ci.org/zfcampus/zf-versioning)[![Coverage Status](https://camo.githubusercontent.com/324a80a7430478b3ba37a358a81f9c07baf9b70837b58074934a7c300df45c85/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f7a6663616d7075732f7a662d76657273696f6e696e672f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/zfcampus/zf-versioning?branch=master)

Introduction
------------

[](#introduction)

zf-versioning is a Zend Framework module for automating service versioning through both URIs and `Accept` or `Content-Type` header media types. Information extracted from either the URI or header media type that relates to versioning will be made available in the route match object. In situations where a controller service name is utilizing a sub-namespace matching the regexp `V(\d)`, the matched controller service names will be updated with the currently matched version string.

Requirements
------------

[](#requirements)

Please see the [composer.json](composer.json) file.

Installation
------------

[](#installation)

Run the following `composer` command:

```
$ composer require zfcampus/zf-versioning
```

Alternately, manually add the following to your `composer.json`, in the `require` section:

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

And then run `composer update` to ensure the module is installed.

Finally, add the module name to your project's `config/application.config.php` under the `modules`key:

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

> ### zf-component-installer
>
> [](#zf-component-installer)
>
> If you use [zf-component-installer](https://github.com/zendframework/zf-component-installer), that plugin will install zf-versioning as a module for you.

Configuration
-------------

[](#configuration)

### User Configuration

[](#user-configuration)

The top-level configuration key for user configuration of this module is `zf-versioning`.

#### Key: `content-type`

[](#key-content-type)

The `content-type` key is used for specifying an array of regular expressions that will be used in parsing both `Content-Type` and `Accept` headers for media type based versioning information. A default regular expression is provided in the implementation which should also serve as an example of what kind of regex to create for more specific parsing:

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

This rule will match the following pseudo-code route:

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

```

All captured parts should utilize named parameters. A more specific example, with the top-level key would look like:

```
'zf-versioning' => [
    'content-type' => [
        '#^application/vendor\.(?Pmwop)\.v(?P\d+)\.(?Pstatus|user)$#',
    ],
],
```

#### Key: `default_version`

[](#key-default_version)

The `default_version` key provides the default version number to use in case a version is not provided by the client. `1` is the default for `default_version`.

The setting accepts one of the two following possible values:

- A PHP `integer` indicating the default version number for *all* routes.
- An associative array, where the keys are route names, and the values the default version to use with the associated route.

Full Example:

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

or

```
// 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,
    ],
],
```

#### Key: `uri`

[](#key-uri)

The `uri` key is responsible for identifying which routes need to be prepended with route matching information for URL based versioning. This key is an array of route names that is used in the ZF2 `router.routes` configuration. If a particular route is a child route, the chain will happen at the top-most ancestor.

The route matching segment consists of a rule of `[/v:version]` while specifying a constraint of digits only for the version parameter.

Example:

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

### System Configuration

[](#system-configuration)

The following configuration is provided in `config/module.config.php` to enable the module to function:

```
'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 Events
----------

[](#zf2-events)

`zf-versioning` provides no new events, but does provide 4 distinct listeners:

#### ZF\\Versioning\\PrototypeRouteListener

[](#zfversioningprototyperoutelistener)

This listener is attached to `ModuleEvent::EVENT_MERGE_CONFIG`. It is responsible for iterating the routes provided in the `zf-versioning.uri` configuration to look for corresponding routes in the `router.routes` configuration. When a match is detected, this listener will apply the versioning route match configuration to the route configuration.

#### ZF\\Versioning\\VersionListener

[](#zfversioningversionlistener)

This listener is attached to the `MvcEvent::EVENT_ROUTE` at a priority of `-41`. This listener is responsible for updating controller service names that utilize a versioned namespace naming scheme. For example, if the currently matched route provides a controller name such as `Foo\V1\Bar`, and the currently selected version through URL or media type is `4`, then the controller service name will be updated in the route matches to `Foo\V4\Bar`;

#### ZF\\Versioning\\AcceptListener

[](#zfversioningacceptlistener)

This listener is attached to the `MvcEvent::EVENT_ROUTE` at a priority of `-40`. This listener is responsible for parsing out information from the provided regular expressions (see the `content-type` configuration key for details) from any `Accept` header that is present in the request, and assigning that information to the route match, with the regex parameter names as keys.

#### ZF\\Versioning\\ContentTypeListener

[](#zfversioningcontenttypelistener)

This listener is attached to the `MvcEvent::EVENT_ROUTE` at a priority of `-40`. This listener is responsible for parsing out information from the provided regular expressions (see the `content-type` configuration key for details) from any `Content-Type` header that is present in the request, and assigning that information to the route match, with the regex parameter names as keys.

ZF2 Services
------------

[](#zf2-services)

`zf-versioning` provides no unique services other than those that serve the purpose of event listeners, namely:

- `ZF\Versioning\VersionListener`
- `ZF\Versioning\AcceptListener`
- `ZF\Versioning\ContentTypeListener`

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance17

Infrequent updates — may be unmaintained

Popularity47

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 83% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~111 days

Recently: every ~256 days

Total

16

Last Release

2937d ago

Major Versions

0.9.1 → 1.0.0beta12014-03-18

PHP version history (5 changes)0.6.0PHP >=5.3.3

0.8.0PHP >=5.4.8

0.9.0PHP >=5.3.23

1.1.0PHP >=5.5

1.2.0PHP ^5.6 || ^7.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/296074?v=4)[Zend Framework](/maintainers/zendframework)[@zendframework](https://github.com/zendframework)

---

Top Contributors

[![weierophinney](https://avatars.githubusercontent.com/u/25943?v=4)](https://github.com/weierophinney "weierophinney (122 commits)")[![ralphschindler](https://avatars.githubusercontent.com/u/76674?v=4)](https://github.com/ralphschindler "ralphschindler (9 commits)")[![matiasfuster](https://avatars.githubusercontent.com/u/10004100?v=4)](https://github.com/matiasfuster "matiasfuster (7 commits)")[![adamculp](https://avatars.githubusercontent.com/u/284451?v=4)](https://github.com/adamculp "adamculp (3 commits)")[![michaelmoussa](https://avatars.githubusercontent.com/u/183833?v=4)](https://github.com/michaelmoussa "michaelmoussa (2 commits)")[![michalbundyra](https://avatars.githubusercontent.com/u/7423207?v=4)](https://github.com/michalbundyra "michalbundyra (1 commits)")[![kanellov](https://avatars.githubusercontent.com/u/1442736?v=4)](https://github.com/kanellov "kanellov (1 commits)")[![samsonasik](https://avatars.githubusercontent.com/u/459648?v=4)](https://github.com/samsonasik "samsonasik (1 commits)")[![ezimuel](https://avatars.githubusercontent.com/u/475967?v=4)](https://github.com/ezimuel "ezimuel (1 commits)")

---

Tags

restzendZendFrameworkzfmodule

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zfcampus-zf-versioning/health.svg)

```
[![Health](https://phpackages.com/badges/zfcampus-zf-versioning/health.svg)](https://phpackages.com/packages/zfcampus-zf-versioning)
```

###  Alternatives

[zfr/zfr-cors

Zend Framework module that let you deal with CORS requests

611.2M3](/packages/zfr-zfr-cors)[zfr/zfr-rest

Zend Framework 2 REST Module.

8120.6k](/packages/zfr-zfr-rest)[hrevert/ht-img-module

Image manipulation module for Zend Framework 2

1829.6k2](/packages/hrevert-ht-img-module)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)