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