README

a small yet useful library to manage semantic versioning.

Installation

the library can be installed via composer:

composer.phar require sclable/version-comparison

Usage

direct version comparison

Compare a version A with a version B.

Example:

$a = \Sclable\VersionComparison\Version::create('1.1.0');
$b = \Sclable\VersionComparison\Version::create('1.2.0');

echo $a->isGreaterThan($b) ? 'TRUE' : 'FALSE'; // echoes FALSE
echo $a->isLessThan($b) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $a->isEqual($b) ? 'TRUE' : 'FALSE'; // echoes FALSE
echo $a->isNotEqual($b) ? 'TRUE' : 'FALSE'; // echoes TRUE

version sorting

Sort a list of version to their semantic order. There are two sorter callbacks available, one to sort a list of Version objects, one to sort a list of version strings:

\Sclable\VersionComparison\Version::getVersionSorter($order = Version::SORT_ASC)
- sort a list of version objects
- $order defines whether to sort ascending or descending, use the SORT_* constants to select the desired result
\Sclable\VersionComparison\Version::getVersionStringSorter($order = Version::SORT_ASC)
- sort a list of version strings
- $order defines whether to sort ascending or descending, use the SORT_* constants to select the desired result

Example:

$sort = [
    '1.2.0',
    '1.1.0',
    '1.0.0',
    '1.3.0-alpha',
    '1.3.0',
    '1.3.0-beta1',
    '1.3.0-beta2',
    '1.3.0-beta',
    '1.3.0-rc',
    '1.4.0'
];

usort($sort, \Sclable\VersionComparison\Version::getVersionStringSorter();

var_dump($sort);

/*
array (
    '1.0.0',
    '1.1.0',
    '1.2.0',
    '1.3.0-alpha',
    '1.3.0-beta',
    '1.3.0-beta1',
    '1.3.0-beta2',
    '1.3.0-rc',
    '1.3.0',
    '1.4.0'
)
*/

version selector

A version selector describes what a version should be like, e.g.: greater than 1.1, stable, but below version 2.0. So a version selector like ^1.2.3 would allow all stable versions greater or equal than 1.2.3, but not any version of 2.*.

$selector = \Sclable\VersionComparison\VersionSelector::create('^1.1');
$a = \Sclable\VersionComparison\Version::create('1.2.3');
$b = \Sclable\VersionComparison\Version::create('1.4.0');
$c = \Sclable\VersionComparison\Version::create('2.0.0');

echo $selector->matches($a) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($b) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($c) ? 'TRUE' : 'FALSE'; // echoes FALSE

exact selector

1.2.3

This selector requires an exact match of a version.

$selector = \Sclable\VersionComparison\VersionSelector::create('1.2.3');
$a = \Sclable\VersionComparison\Version::create('1.2.3');
$b = \Sclable\VersionComparison\Version::create('1.2.4');

echo $selector->matches($a) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($b) ? 'TRUE' : 'FALSE'; // echoes FALSE

wildcard selector

1.2.*

This selector requires the version numbers before the wildcard to match.

$selector = \Sclable\VersionComparison\VersionSelector::create('1.2.*');
$a = \Sclable\VersionComparison\Version::create('1.2.3');
$b = \Sclable\VersionComparison\Version::create('1.2.4');
$c = \Sclable\VersionComparison\Version::create('1.3.0');

echo $selector->matches($a) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($b) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($c) ? 'TRUE' : 'FALSE'; // echoes FALSE

tilde selector

~1.2.3

This selector requires the version to be bigger or equal than the defined number, but the numbers before the last one will not match, if increased. Thus for the example above, version 1.2.0 would be too low, version 1.2.3 would be the lowest to select, version 1.2.9 would be fine too, but version 1.3.0 or higher would not match anymore. A selector like ~1 would be the same as 1.*.

$selector = \Sclable\VersionComparison\VersionSelector::create('~1.2.3');
$a = \Sclable\VersionComparison\Version::create('1.2.0');
$b = \Sclable\VersionComparison\Version::create('1.2.3');
$c = \Sclable\VersionComparison\Version::create('1.2.5');
$d = \Sclable\VersionComparison\Version::create('1.3.0');

echo $selector->matches($a) ? 'TRUE' : 'FALSE'; // echoes FALSE
echo $selector->matches($b) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($c) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($d) ? 'TRUE' : 'FALSE'; // echoes FALSE

caret selector

^1.2.3

This selector requires the version to be bigger or equal than the defined number, but below the next major release. Thus for the example above, version 1.2.0 would be too low, version 1.2.3 would be the lowest to select, version 1.4.2 would be fine too, but version 2.0.0 or higher would not match anymore.

$selector = \Sclable\VersionComparison\VersionSelector::create('^1.2.3');
$a = \Sclable\VersionComparison\Version::create('1.2.0');
$b = \Sclable\VersionComparison\Version::create('1.2.3');
$c = \Sclable\VersionComparison\Version::create('1.4.2');
$d = \Sclable\VersionComparison\Version::create('2.0.0');

echo $selector->matches($a) ? 'TRUE' : 'FALSE'; // echoes FALSE
echo $selector->matches($b) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($c) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $selector->matches($d) ? 'TRUE' : 'FALSE'; // echoes FALSE

stability modifier

1.2.3-dev

This modifies the desired stability. Default stability is stable. The modifier can be applied to all selectors.

$stable = \Sclable\VersionComparison\VersionSelector::create('1.2.3');
$dev = \Sclable\VersionComparison\VersionSelector::create('1.2.3-dev');

$a = \Sclable\VersionComparison\Version::create('1.2.3');
$b = \Sclable\VersionComparison\Version::create('1.2.3-beta');

echo $stable->matches($a) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $stable->matches($b) ? 'TRUE' : 'FALSE'; // echoes FALSE
echo $dev->matches($a) ? 'TRUE' : 'FALSE'; // echoes TRUE
echo $dev->matches($b) ? 'TRUE' : 'FALSE'; // echoes TRUE

version pool

The version pool is useful to match a set of versions against a selector.

select

Select all matching versions from the pool.

$pool = \Sclable\VersionComparison\VersionPool::create([
    '1.0.0', '1.2.3', '1.4.2', '2.0.0'
]);

foreach ($pool->select('^1.1.0') as $version) {
    echo $version->getVersion() . PHP_EOL;
}

// prints
// 1.2.3
// 1.4.2

select all

Select all versions matching all selectors from the pool.

$pool = \Sclable\VersionComparison\VersionPool::create([
    '1.0.0', '1.2.3', '1.4.2', '2.0.0'
]);

$matches = $pool->selectAll(['^1.0', '1.2.*']);

foreach ($matches as $version) {
    echo $version->getVersion() . PHP_EOL;
}

// prints
// 1.2.3

match

This little helper is useful to simplify code:

$pool = \Sclable\VersionComparison\VersionPool::create([
    '1.0.0', '1.2.3', '1.4.2', '2.0.0'
]);

if ($pool->match('^1.1.0', $matches)) {
    // we have one or more matches, let's do something with it
} else {
    // the selector does not match any version. we can skip the hard work.
}

get best match

Searches the pool for the best match for a selector.

$pool = \Sclable\VersionComparison\VersionPool::create([
        '1.0.0', '1.2.3', '1.4.2', '2.0.0'
]);

$best = $pool->getBestMatch('^1.1.0');

echo $best->getVersion();

// prints
// 1.4.2

selector collection

Selectors can be combined and still matched against Version or VersionPools:

$selectorA = \Sclable\VersionComparison\VersionSelector::create('^1.0.0');
$selectorB = \Sclable\VersionComparison\VersionSelector::create('~1.2.3');

$collection = \Sclable\VersionComparison\VersionSelectorCollection::create([
    $selectorA, $selectorB
]);

$version = \Sclable\VersionComparison\Version::create('1.2.4');

echo $collection->matches($version) ? 'TRUE' : 'FALSE'; // echoes TRUE

API Documentation

A basic api documentation is located here: doc/ApiIndex.md

sclable / version-comparison

Maintainers

Details