rnd-cosoft/api-tools-versioning

Laminas Module providing listeners and route prototypes for implementing API versioning

1.8.1 2024-05-10 08:01 UTC

README

Build Status

πŸ‡·πŸ‡Ί Русским Π³Ρ€Π°ΠΆΠ΄Π°Π½Π°ΠΌ

ΠœΡ‹, участники 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