README

This PHP library parse any version syntax, including semantic version. It allows also to compare versions, using Composer version constraints syntax.

installation

You can install it from Composer. In your project:

composer require "jelix/version"

Usage

Parsing

Use the Jelix\Version\Parser class to retrieve a Jelix\Version\Version object containing all versions informations.

$version = \Jelix\Version\Parser::parse('1.2.3b2');

$version->toString(); // '1.2.3-beta.2'
$version->getMajor(); // 1
$version->getMinor(); // 2
$version->getPatch(); // 3
$version->getStabilityVersion(); // array('beta', '2')

$version->getNextMajorVersion(); // Version object for '2.0.0'
$version->getNextMinorVersion(); // Version object for '1.3.0'
$version->getNextPatchVersion(); // Version object for '1.2.4'
$version->getBranchVersion(); // '1.2'

Example of supported version syntaxes:

1.0, 1.2.3
1.2-alpha, 1.2a, 1.2alpha, 1.2alpha.3, 1.2a1.3
1.2.3-beta, 1.2b, 1.2beta, 1.2beta.3, 1.2b3.4
1.2RC, 1.2-rc.4.5
1.2-dev, 1.2b1-dev, 1.2b1-dev.9, 1.2RC-dev, 1.2RC2-dev.1700

The parser support also 'secondary versions', i.e. versions appended to a version after a - or a :.

Ex: 1.2.3-1.4.5, 1.2.3:1.4.5. Here, 1.4.5 is a secondary version.

When retrieving a Version object for such versions, you can access to the secondary version through a method getSecondaryVersion() which returns a Version object:

$version = \Jelix\Version\Parser::parse('1.2.3:1.4.5');

$version->toString(); // '1.2.3:1.4.5'
$version->toString(true, false); // '1.2.3'

$version2 = $version->getSecondaryVersion();
$version2->toString(); // '1.4.5'

$version->getNextMajorVersion(); // Version object for '2.0.0'
$version->getNextMinorVersion(); // Version object for '1.3.0'
$version->getNextPatchVersion(); // Version object for '1.2.4'
$version->getBranchVersion(); // '1.2'

Simple comparison

$v1 = '1.2.3';
$v2 = '1.4.5';
$result = \Jelix\Version\VersionComparator::compareVersion($v1, $v2);

compareVersion() returns:

-1 if $v1 < $v2
0 if $v1 == $v2
1 if $v1 > $v2

Example to compare two versions:

\Jelix\Version\VersionComparator::compareVersion('1.2pre','1.2RC');

Secondary versions are also compared if primary versions are equals. In this case, if one of the version string does not contain a secondary version, then it is considered having the '0.0' version number, so it is considered as lower version than the version having a secondary version.

You have also an other method compare() taking Version objects as parameters:

$v1 = \Jelix\Version\Parser::parse('1.2.3');
$v2 = \Jelix\Version\Parser::parse('1.4.5');
$result = \Jelix\Version\VersionComparator::compare($v1, $v2);

Comparison with range

compareVersionRange() allows you to use operator to compare version. It is compatible with version constraints supported by Composer.

comparison operators: >, <, >=, <=, =, !=
no operator means =
~ : specify a range between the version and the next major version (excluding the next major version itself and its unstable variant)
- ~1.2 is equivalent to >=1.2 <2.0.0-dev
- ~1.2.3 is equivalent to >=1.2.3 <1.3.0-dev
'^' : specify a range between the version and the next minor version
- ^1.2.3 is equivalent to >=1.2.3 <1.3.0
- ^0.3 is equivalent to >=0.3.0 <0.4.0
hyphen separator to specify a range : '1.2 - 1.5'
- 1.0 - 2.0 is equivalent to >=1.0.0 <2.1 (as 2.0 is interpreted as 2.0.*)
- 1.0.0 - 2.1.0 is equivalent to >=1.0.0 <=2.1.0
It supports also version wildcards with or without operators: 1.*, 1.2.*

You can combine several constraints with boolean operators :

AND operator: , or
OR operator: || or |.

// check if 0.5 is between 0.8 and 1.0 or if it is higher than 2.0
\Jelix\Version\VersionComparator::compareVersionRange('0.5','<1.0,>0.8|>2.0');

// check if 0.5 is between 0.8 and 1.0
\Jelix\Version\VersionComparator::compareVersionRange('0.5','0.8 - 1.0');

// with a wildcard
\Jelix\Version\VersionComparator::compareVersionRange('1.1', '1.1.*'); // returns true
\Jelix\Version\VersionComparator::compareVersionRange('1.1.2', '1.2.*'); // returns false
\Jelix\Version\VersionComparator::compareVersionRange('1.3.0', '>=1.2.*'); // returns true

Note: comparison with a range is done only on primary version. If a version string contains a secondary version, this secondary version is not compared. To compare a secondary version with a range, you should retrieve the secondary version with the getSecondaryVersion() method.

$version = Jelix\Version\Parser::parse('1.2.3:1.0.0');

\Jelix\Version\VersionComparator::compareVersionRange($version, '>=1.2.*'); // returns true

$version2 = $version->getSecondaryVersion();
$version2->toString(); // '1.0.0'

\Jelix\Version\VersionComparator::compareVersionRange($version2, '>=1.2.*'); // returns false

History

Ancesters of these classes have been included for years into the Jelix Framework until Jelix 1.6, and has been released in 2016 into a separate repository.

jelix / version

Maintainers

Details