laminas-api-tools / api-tools-versioning
Laminas Module providing listeners and route prototypes for implementing API versioning
Fund package maintenance!
Community Bridge
Installs: 1 278 037
Dependents: 3
Suggesters: 0
Security: 0
Stars: 9
Watchers: 10
Forks: 14
Open Issues: 3
Requires
- php: ~8.0.0 || ~8.1.0 || ~8.2.0
- laminas/laminas-eventmanager: ^3.2
- laminas/laminas-http: ^2.5.4
- laminas/laminas-modulemanager: ^2.7.2
- laminas/laminas-mvc: ^2.7.15 || ^3.0.2
- laminas/laminas-servicemanager: ^3.11
- laminas/laminas-stdlib: ^2.7.7 || ^3.0.1
Requires (Dev)
- laminas/laminas-coding-standard: ~2.3.0
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^9.5.10
- psalm/plugin-phpunit: ^0.16.1
- vimeo/psalm: ^4.13.1
Conflicts
README
π·πΊ Π ΡΡΡΠΊΠΈΠΌ Π³ΡΠ°ΠΆΠ΄Π°Π½Π°ΠΌ
ΠΡ, ΡΡΠ°ΡΡΠ½ΠΈΠΊΠΈ Laminas, ΡΠΎΠ΄ΠΈΠ»ΠΈΡΡ ΠΈ ΠΆΠΈΠ²Π΅ΠΌ Π² ΡΠ°Π·Π½ΡΡ ΡΡΡΠ°Π½Π°Ρ . Π£ ΠΌΠ½ΠΎΠ³ΠΈΡ ΠΈΠ· Π½Π°Ρ Π΅ΡΡΡ Π΄ΡΡΠ·ΡΡ, ΡΠΎΠ΄ΡΡΠ²Π΅Π½Π½ΠΈΠΊΠΈ ΠΈ ΠΊΠΎΠ»Π»Π΅Π³ΠΈ ΠΊΠ°ΠΊ Π² Π ΠΎΡΡΠΈΠΈ, ΡΠ°ΠΊ ΠΈ Π² Π£ΠΊΡΠ°ΠΈΠ½Π΅. ΠΠ΅ΠΊΠΎΡΠΎΡΡΠ΅ ΠΈΠ· Π½Π°Ρ ΡΠΎΠ΄ΠΈΠ»ΠΈΡΡ Π² Π ΠΎΡΡΠΈΠΈ. ΠΠ΅ΠΊΠΎΡΠΎΡΡΠ΅ ΠΈΠ· Π½Π°Ρ ΠΆΠΈΠ²ΡΡ Π² Π ΠΎΡΡΠΈΠΈ. Π£ Π½Π΅ΠΊΠΎΡΠΎΡΡΡ Π±Π°Π±ΡΡΠΊΠΈ ΠΈ Π΄Π΅Π΄ΡΡΠΊΠΈ ΡΡΠ°ΠΆΠ°Π»ΠΈΡΡ Ρ ΡΠ°ΡΠΈΡΡΠ°ΠΌΠΈ Π²ΠΎ ΠΡΠΎΡΠΎΠΉ ΠΌΠΈΡΠΎΠ²ΠΎΠΉ Π²ΠΎΠΉΠ½Π΅. ΠΠ΄Π΅ΡΡ Π½ΠΈΠΊΡΠΎ Π½Π΅ ΠΏΠΎΠ΄Π΄Π΅ΡΠΆΠΈΠ²Π°Π΅Ρ ΡΠ°ΡΠΈΠ·ΠΌ.
Π£ ΠΎΠ΄Π½ΠΎΠ³ΠΎ ΠΈΠ· Π½Π°Ρ Π΅ΡΡΡ ΡΠΊΡΠ°ΠΈΠ½ΡΠΊΠ°Ρ ΡΠΎΠ΄ΡΡΠ²Π΅Π½Π½ΠΈΡΠ°, ΠΊΠΎΡΠΎΡΠ°Ρ ΡΠΏΠ°ΡΠ»Π°ΡΡ ΠΈΠ· Π΄ΠΎΠΌΠ° Π²ΠΌΠ΅ΡΡΠ΅ Ρ ΡΡΠ½ΠΎΠΌ. ΠΠΎΠ΅Π·Π΄ Π·Π°Π΄Π΅ΡΠΆΠ°Π»ΡΡ ΠΈΠ·-Π·Π° Π±ΠΎΠΌΠ±Π΅ΠΆΠΊΠΈ Π½Π° Π΄ΠΎΡΠΎΠ³Π΅ Π²ΠΏΠ΅ΡΠ΅Π΄ΠΈ. Π£ Π½Π°Ρ Π΅ΡΡΡ Π΄ΡΡΠ·ΡΡ, ΠΊΠΎΡΠΎΡΡΠ΅ ΠΏΡΡΡΡΡΡΡ Π² Π±ΠΎΠΌΠ±ΠΎΡΠ±Π΅ΠΆΠΈΡΠ°Ρ . ΠΡ Ρ ΡΡΠ΅Π²ΠΎΠ³ΠΎΠΉ ΠΆΠ΄Π΅ΠΌ Π²Π΅ΡΡΠΎΡΠΊΠΈ ΠΎΡ Π½ΠΈΡ ΠΏΠΎΡΠ»Π΅ Π²ΠΎΠ·Π΄ΡΡΠ½ΡΡ Π½Π°Π»Π΅ΡΠΎΠ², ΠΊΠΎΡΠΎΡΡΠ΅ Π±Π΅ΡΠΏΠΎΡΡΠ΄ΠΎΡΠ½ΠΎ Π½Π°Π½ΠΎΡΡΡ ΡΠ΄Π°ΡΡ ΠΈ ΠΏΠΎΠΏΠ°Π΄Π°ΡΡ ΠΏΠΎ Π±ΠΎΠ»ΡΠ½ΠΈΡΠ°ΠΌ, ΡΠΊΠΎΠ»Π°ΠΌ, Π΄Π΅ΡΡΠΊΠΈΠΌ ΡΠ°Π΄Π°ΠΌ ΠΈ Π΄ΠΎΠΌΠ°ΠΌ. ΠΡ Π½Π΅ Π±Π΅ΡΠ΅ΠΌ ΡΡΠΎ ΠΈΠ· ΠΊΠ°ΠΊΠΈΡ -Π»ΠΈΠ±ΠΎ Π‘ΠΠ. ΠΡ Π½Π°Π±Π»ΡΠ΄Π°Π΅ΠΌ ΡΡΠΎ Π½Π°ΠΏΡΡΠΌΡΡ.
ΠΡ Π΄ΠΎΠ²Π΅ΡΡΠ΅ΡΠ΅ Π½Π°ΠΌ Π΄ΠΎΡΡΠ°ΡΠΎΡΠ½ΠΎ, ΡΡΠΎΠ± ΠΈΡΠΏΠΎΠ»ΡΠ·ΠΎΠ²Π°ΡΡ Π½Π°ΡΠΈ ΠΏΡΠΎΠ³ΡΠ°ΠΌΠΌΡ, ΠΈ ΠΌΡ ΠΏΡΠΎΡΠΈΠΌ Π²Π°Ρ Π΄ΠΎΠ²Π΅ΡΠΈΡΡΡΡ Π½Π°ΠΌ Π²Π½ΠΎΠ²Ρ. ΠΡ Π½ΡΠΆΠ΄Π°Π΅ΠΌΡΡ Π² ΠΏΠΎΠΌΠΎΡΠΈ. ΠΡΡ ΠΎΠ΄ΠΈΡΠ΅ ΠΈ ΠΏΡΠΎΡΠ΅ΡΡΡΠΉΡΠ΅ ΠΏΡΠΎΡΠΈΠ² ΡΡΠΎΠΉ Π±Π΅ΡΠΏΠΎΠ»Π΅Π·Π½ΠΎΠΉ Π²ΠΎΠΉΠ½Ρ. ΠΡΡΠ°Π½ΠΎΠ²ΠΈΡΠ΅ ΠΊΡΠΎΠ²ΠΎΠΏΡΠΎΠ»ΠΈΡΠΈΠ΅. Π‘ΠΊΠ°ΠΆΠΈΡΠ΅ "ΠΠ΅Ρ Π²ΠΎΠΉΠ½Π΅!"
πΊπΈ To Citizens of Russia
We at Laminas come from all over the world. Many of us have friends, family and colleagues in both Russia and Ukraine. Some of us were born in Russia. Some of us currently live in Russia. Some have grandparents who fought Nazis in World War II. Nobody here supports fascism.
One team member has a Ukrainian relative who fled her home with her son. The train was delayed due to bombing on the road ahead. We have friends who are hiding in bomb shelters. We anxiously follow up on them after the air raids, which indiscriminately fire at hospitals, schools, kindergartens and houses. We're not taking this from any media. These are our actual experiences.
You trust us enough to use our software. We ask that you trust us to say the truth on this. We need your help. Go out and protest this unnecessary war. Stop the bloodshed. Say "stop the war!"
Introduction
api-tools-versioning is a Laminas 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
Please see the composer.json file.
Installation
Run the following composer
command:
$ composer require laminas-api-tools/api-tools-versioning
Alternately, manually add the following to your composer.json
, in the require
section:
"require": { "laminas-api-tools/api-tools-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' => [ /* ... */ 'Laminas\ApiTools\Versioning', ], /* ... */ ];
laminas-component-installer
If you use laminas-component-installer, that plugin will install api-tools-versioning as a module for you.
Configuration
User Configuration
The top-level configuration key for user configuration of this module is api-tools-versioning
.
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<laminas_ver_vendor>[^.]+)\.v(?P<laminas_ver_version>\d+)\.(?P<laminas_ver_resource>[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:
'api-tools-versioning' => [ 'content-type' => [ '#^application/vendor\.(?P<vendor>mwop)\.v(?P<version>\d+)\.(?P<resource>status|user)$#', ], ],
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 'api-tools-versioning' => [ 'default_version' => 2, ],
or
// 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, ], ],
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 Laminas
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:
'api-tools-versioning' => [ 'uri' => [ 'api', 'status', 'user', ], ],
System Configuration
The following configuration is provided in config/module.config.php
to enable the module to
function:
'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 Events
api-tools-versioning
provides no new events, but does provide 4 distinct listeners:
Laminas\ApiTools\Versioning\PrototypeRouteListener
This listener is attached to ModuleEvent::EVENT_MERGE_CONFIG
. It is responsible for iterating the
routes provided in the api-tools-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.
Laminas\ApiTools\Versioning\VersionListener
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
;
Laminas\ApiTools\Versioning\AcceptListener
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.
Laminas\ApiTools\Versioning\ContentTypeListener
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.
Laminas Services
api-tools-versioning
provides no unique services other than those that serve the purpose
of event listeners, namely:
Laminas\ApiTools\Versioning\VersionListener
Laminas\ApiTools\Versioning\AcceptListener
Laminas\ApiTools\Versioning\ContentTypeListener