1# php-semver -- The semantic versioner for npm ported to PHP 2 3Ported from [node-semver 1.1.2](https://github.com/isaacs/node-semver/tree/v1.1.2) to PHP 4 5[![Build Status](https://secure.travis-ci.org/vierbergenlars/php-semver.png?branch=master)](http://travis-ci.org/vierbergenlars/php-semver) 6 7## Usage 8 9```php 10<?php 11 12use vierbergenlars\SemVer\version; 13use vierbergenlars\SemVer\expression; 14use vierbergenlars\SemVer\SemVerException; 15 16// Check if a version is valid 17$semver = new version('1.2.3'); 18$semver = new version('a.b.c'); //SemVerException thrown 19 20//Get a clean version string 21$semver = new version('=v1.2.3'); 22$semver->getVersion(); //'1.2.3' 23 24//Check if a version satisfies a range 25$semver = new version('1.2.3'); 26$semver->satisfies(new expression('1.x || >=2.5.0 || 5.0.0 - 7.2.3')); //true 27# OR 28$range = new expression('1.x || >=2.5.0 || 5.0.0 - 7.2.3'); 29$range->satisfiedBy(new version('1.2.3')); //true 30 31//Compare two versions 32version::gt('1.2.3', '9.8.7'); //false 33version::lt('1.2.3', '9.8.7'); //true 34``` 35 36## Versions 37 38A version is the following things, in this order: 39 40* a number (Major) 41* a period 42* a number (minor) 43* a period 44* a number (patch) 45* OPTIONAL: a hyphen, followed by a number (build) 46* OPTIONAL: a collection of pretty much any non-whitespace characters 47 (tag) 48 49A leading `"="` or `"v"` character is stripped off and ignored. 50 51## Comparisons 52 53The ordering of versions is done using the following algorithm, given 54two versions and asked to find the greater of the two: 55 56* If the majors are numerically different, then take the one 57 with a bigger major number. `2.3.4 > 1.3.4` 58* If the minors are numerically different, then take the one 59 with the bigger minor number. `2.3.4 > 2.2.4` 60* If the patches are numerically different, then take the one with the 61 bigger patch number. `2.3.4 > 2.3.3` 62* If only one of them has a build number, then take the one with the 63 build number. `2.3.4-0 > 2.3.4` 64* If they both have build numbers, and the build numbers are numerically 65 different, then take the one with the bigger build number. 66 `2.3.4-10 > 2.3.4-9` 67* If only one of them has a tag, then take the one without the tag. 68 `2.3.4 > 2.3.4-beta` 69* If they both have tags, then take the one with the lexicographically 70 larger tag. `2.3.4-beta > 2.3.4-alpha` 71* At this point, they're equal. 72 73## Ranges 74 75The following range styles are supported: 76 77* `>1.2.3` Greater than a specific version. 78* `<1.2.3` Less than 79* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` 80* `~1.2.3` := `>=1.2.3 <1.3.0` 81* `~1.2` := `>=1.2.0 <2.0.0` 82* `~1` := `>=1.0.0 <2.0.0` 83* `1.2.x` := `>=1.2.0 <1.3.0` 84* `1.x` := `>=1.0.0 <2.0.0` 85 86Ranges can be joined with either a space (which implies "and") or a 87`||` (which implies "or"). 88 89## Functions 90 91* `$version->valid()`: Return the parsed version, or null if it's not valid. 92* `$version->inc($type)`: Return the version incremented by the release type 93 (major, minor, patch, or build), or null if an invalid release type is provided. 94 95### Comparison 96 97* `version::gt($v1, $v2)`: `v1 > v2` 98* `version::gte($v1, $v2)`: `v1 >= v2` 99* `version::lt($v1, $v2)`: `v1 < v2` 100* `version::lte($v1, $v2)`: `v1 <= v2` 101* `version::eq($v1, $v2)`: `v1 == v2` This is true if they're logically equivalent, 102 even if they're not the exact same string. You already know how to 103 compare strings. 104* `version::neq($v1, $v2)`: `v1 != v2` The opposite of eq. 105* `version::cmp($v1, $comparator, $v2)`: Pass in a comparison string, and it'll call 106 the corresponding function above. `"==="` and `"!=="` do simple 107 string comparison, but are included for completeness. Throws if an 108 invalid comparison string is provided. 109* `version::compare($v1, $v2)`: Return 0 if `v1 == v2`, 1 if `v1 > v2`, or -1 if 110 `v1 < v2`. Sorts in ascending order if passed to [`usort()`](http://php.net/manual/en/function.usort.php) 111* `version::rcompare($v1, $v2)`: The reverse of compare. Sorts an array of versions 112 in descending order when passed to [`usort()`](http://php.net/manual/en/function.usort.php). 113 114 115### Ranges 116 117* `$expression->validRange()`: Return the valid range or `null` if it's not valid 118* `$version->satisfies($range)`: Return `true` if the version satisfies the range. 119* `$expression->maxSatisfying($versions)`: Return the highest version in the array 120 that satisfies the range, or `null` if none of them do. 121 122## Thanks to 123 124All contributors (https://github.com/vierbergenlars/php-semver/graphs/contributors) 125 126[@isaacs](https://github.com/isaacs) and other contributors to [node-semver](https://github.com/isaacs/node-semver) 127