sclable / version-comparison
A small library to compare version information.
Requires (Dev)
- evert/phpdoc-md: ^0.1.1
- phpunit/phpunit: ^4.7
- sclable/coding-standards: 0.1.0.2
This package is not auto-updated.
Last update: 2016-06-29 12:33:06 UTC
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
License
For the license and copyright see the LICENSE file.