vltpkg / semantic-versions
Parse, compare and match versions per the Semantic Versions specification (semver.xyz)
Requires
- php: >=8.1
Requires (Dev)
- composer/semver: ^3.4
- z4kn4fein/php-semver: ^3.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-20 20:38:45 UTC
README
The PHP implementation of Semantic Versions: parse, validate, compare and range-match version numbers, with builds that participate in precedence.
It is a port of the JavaScript reference implementation
(semantic-versions on npm)
and behaves identically: both pass the same
conformance suite,
and they agree on every version, range and resolution in the benchmark corpus.
PHP 8.1+, no dependencies.
Install
composer require vltpkg/semantic-versions
Usage
use Vlt\SemanticVersions\Range; use Vlt\SemanticVersions\SemanticVersions as SV; use Vlt\SemanticVersions\Version; $v = Version::parse('1.2.3-beta.4+build.7'); // $v->major === 1, $v->prerelease === 'beta.4', $v->build === 'build.7' // Builds participate in precedence: a build ranks above its plain release. Version::parse('1.0.0')->compare(Version::parse('1.0.0+build.1')); // -1 SV::satisfies('1.4.0', '^1.2.3'); // true SV::satisfies('1.0.0-rc.1', '^1.0.0-rc'); // true: pre-release channel SV::satisfies('1.0.0-beta', '^1.0.0-rc'); // false: a different channel SV::satisfies('1.4.2+win.x64', '^1.0.0+win'); // true: build channel SV::validRange('~>1.2'); // '>=1.2.0 <1.3.0-0' // Contexts scope a version or range to an identity. $react = Range::parse('npm:react@^18'); $react->test(Version::parse('npm:react@18.2.0')); // true $react->test(Version::parse('composer:react@18.2.0')); // false SV::maxSatisfying(['1.0.0', '1.9.0', '2.0.0'], '^1'); // '1.9.0'
Version::parse and Range::parse throw SemanticVersionException;
tryParse returns null instead.
How this differs from composer/semver and z4kn4fein/php-semver
- Builds participate in precedence (
1.0.0 < 1.0.0+build), and a build on a comparator is a channel filter. - Pre-releases are range-driven: a pre-release on a comparator is a
prefix channel scoped to its
tuple;
X.Y.Z-*and*-*opt in explicitly. - Contexts:
npm:react@18.2.0,npm:@babel/core@^7. - No coercion:
v1.2.3and1.2are errors. - No stability flags or four-part versions:
1.0.0-rc.1stays1.0.0-rc.1rather than becoming Composer's1.0.0.0-RC1, and any pre-release name is allowed.
Performance and conformance
Compared with composer/semver and z4kn4fein/php-semver on real versions and dependency ranges from the npm registry. Method and raw
results: benchmarks/.
All implementations: semver.xyz/libraries.
Speed
| Operation | semantic-versions@1.0.0 |
composer/semver@3.6.0 |
z4kn4fein/php-semver@3.0.0 |
semantic-versions vs composer/semver |
|---|---|---|---|---|
| Parse a version | 354 ns | 819 ns | 664 ns | 2.3× faster |
| Sort versions | 1.55 µs | 1.63 µs | 2.16 µs | 1.1× faster |
| Parse a range | 2.23 µs | 2.40 µs | 3.65 µs | 1.1× faster |
| range->test(version) | 169 ns | 621 ns | 474 ns | 3.7× faster |
| Resolve a range | 26.7 µs | 101.9 µs | 71.0 µs | 3.8× faster |
Median time per operation (lower is better) on 5,398 published versions and 797 dependency ranges from the npm registry. PHP 8.3.6 · Intel(R) Xeon(R) Processor @ 2.30GHz · linux x86_64 · 2026-11-19. composer/semver: Composer's model differs by design: versions normalize to four parts with stability flags (1.0.0-rc.1 becomes 1.0.0.0-RC1), builds are dropped, and pre-release names outside alpha, beta, RC and patch are rejected. Versions are scored on parsing to the same value.
Conformance
| Semantic Versions feature | semantic-versions |
composer/semver |
z4kn4fein/php-semver |
|---|---|---|---|
| Version grammar Valid and invalid versions per the BNF |
✓ 81/81 | ◐ 57/81 | ◐ 80/81 |
| No coercion Rejects v1.2.3, =1.2.3, 1.2.3pre, … |
✓ 11/11 | ◐ 8/11 | ✓ 11/11 |
| Precedence Major, minor, patch and pre-release ordering |
✓ 32/32 | ◐ 18/32 | ✓ 32/32 |
| Build precedence A build ranks above its release: 1.0.0 < 1.0.0+b |
✓ 10/10 | ◐ 1/10 | ◐ 1/10 |
| Ranges Comparators, ||, x-ranges, ~, ^, hyphen ranges |
✓ 199/199 | ◐ 139/172 | ◐ 164/172 |
| Approximate ranges The pessimistic operator ~> |
✓ 17/17 | ◐ 7/13 | ✓ 13/13 |
Pre-release channels ^1.0.0-rc admits rc.*, never beta |
✓ 44/44 | ◐ 26/44 | ◐ 19/44 |
Pre-release wildcards X.Y.Z-* and *-* opt in explicitly |
✓ 14/14 | ◐ 2/13 | ◐ 2/13 |
Build channels ^1.0.0+win admits +win.* builds only |
✓ 24/24 | ◐ 12/22 | ◐ 12/22 |
Contexts npm:react@18.2.0, npm:react@^18 |
✓ 15/15 | ◐ 3/15 | ◐ 3/15 |
| All cases | 447/447 | 273/413 | 337/413 |
Cases from the shared conformance suite in conformance/, drawn from the specification. ✓ all pass · ◐ some pass · ✗ none pass.
Develop
composer install composer test # conformance suite composer bench # benchmarks
License
Apache-2.0. The specification is at semver.xyz.