Multi-Variant

The Contracts Library is multi-variant. What does that mean?

What Is Multi-Variant?

In a normal library, when you install it via composer, you get one version of the library. You'll choose between version 1.x, version 2.x, version 3.x and so on.

In a multi-variant library, the library includes all of the different versions. You get version 1.x, version 2.x and version 3.x (and so on) installed at the same time. Each version of the library has its own namespace. Your code can use multiple versions at the same time.

The Contracts Library uses these namespaces:

• GanbaroDigital\Contracts\V1 - version 1.x of the library
• GanbaroDigital\Contracts\V2 - reserved for version 2.x of the library

These are the library's API versions.

Why Do We Need Multi-Variant Libraries?

Version 2.x of a library's API is normally incompatible with version 1.x of the same library. This is good practice. Unfortunately, that leads to some problems with PHP's lack of code module support.

• It's currently common practice for version 1.x and version 2.x of a library to re-use the same PHP namespace.
• One part of an app can't use version 1.x of a library, whilst a different part of an app uses version 2.x of the same library.
• It's also currently common practice for Git tags to use the library's API version number. For example, if the library's API is at v2.6.3, the Git tag would also be v2.6.3.
• The Composer package manager has to use the Git tags to work out which version of the library to install.

As a result, the Composer package manager won't let you install both version 1.x and version 2.x of the same library at the same time.

This becomes a blocker when your application has dependencies that use different versions of the same library. All of a sudden, you have conflicts in Composer that you cannot resolve.

Multi-variant libraries avoid this problem entirely.

• As far as Composer is concerned, all the dependencies can use the same tagged version of the library.
• As far as each dependency is concerned, the API version of the library that it needs is installed and available for use.

How Do We Version Multi-Variant Libraries?

Multi-variant libraries use v1.YYYYMMDDRR style for Git tags:

• YYYY is the year the library was released (as four digits)
• MM is the month the library was released (two digits, January is 01)
• DD is the day of the month that the library was released (two digits)
• RR is how many times the library has been released on that day (two digits)

For example: v1.2016041401, or v1.2016041502.

Why are there no '.' between the different parts?

• When you use composer require, it adds a ^X.Y constraint to your list of requirements. This will accept all tags that start with X. It will not accept any tag that starts with X+1 or more.
• If we used v2016.04.14.01 as the tag, composer require would add ^v2016.04 as the constraint. This doesn't make any sense for multi-variant libraries, because 2016 doesn't mean that the library isn't compatible with anything tagged 2015.