Search by

vltpkg / semantic-versions

darcyclarke

Parse, compare and match versions per the Semantic Versions specification (semver.xyz)

v1.0.0 2026-11-19 21:48 UTC

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.3 and 1.2 are errors.
  • No stability flags or four-part versions: 1.0.0-rc.1 stays 1.0.0-rc.1 rather than becoming Composer's 1.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.