ptlis/semantic-version

Tools for working with semantic version numbers.

SemanticVersion

A modular, extensible library for PHP >= 5.6 providing APIs to support parsing & manipulation of semantic version numbers, comparators, ranges & collections., _(*1)

The Semantic Versioning Specification describes the semantics and precedence rules used when parsing & manipulating version numbers etc., _(*2)

, _(*3)

Usage

Parse Version

First create an instance of the VersionEngine:, _(*4)

    use ptlis\SemanticVersion\VersionEngine();

    $engine = new VersionEngine();

Then call the parseVersion method passing a version number:, _(*5)

    $version = $engine->parseVersion('1.5.0-rc.1');

On failure to parse a \RuntimeException will be thrown., _(*6)

Parse Version Range

Again, create an instance of the VersionEngine:, _(*7)

    use ptlis\SemanticVersion\VersionEngine();

    $engine = new VersionEngine();

Then call the parseVersionRange method passing a version range:, _(*8)

    $version = $engine->parseVersion('1.5.0-3.0.0');

As before, on failure to parse a \RuntimeException will be thrown., _(*9)

Versions

The Version class provides a simple value type representing a semantic version number., _(*10)

It provides simple accessors for the components of a semantic version number:, _(*11)

    echo $version->getMajor();  // '1'
    echo $version->getMinor();  // '5'
    echo $version->getPatch();  // '0'
    echo $version->getLabel();  // 'rc.1'

A __toString implementation:, _(*12)

    echo $version;  // '1.5.0-rc.1'

Version also implement SatisfiedByVersionInterface so offer the isSatisfiedBy method which returns true if the versions match., _(*13)

Version Ranges

Version ranges are bundles of objects representing a version range constraint, represented by classes implementing VersionRangeInterface., _(*14)

The simplest version range is a version and a comparator (e.g. >=2.5.3, '<1.0.0'), which is expressed by the ComparatorVersion class., _(*15)

A more complex range would be one with an upper and lower bound (e.g. ~1.0.0, '^1.0.0', '>=1.0.0,<2.0.0' which are all equivalent). This is expressed via the LogicalAnd class wrapping two ComparatorVersion instances., _(*16)

The most complex constraint would be one containing two ranges (e.g. 1.2.5-2.3.2|^4.0.0). This is expressed via Wrapping the two classes implementing VersionRangeInterface., _(*17)

As VersionRangeInterface extends SatisfiedByVersionInterface these implement the isSatisfiedBy method which returns true if the passed version satisfies the constraint., _(*18)

Known limitations

There currently are a few areas where this library deviates from the specification when dealing with labels & build metadata; this is to due to how the parsing of version-ranges is handled. However, having tested the parsing code against the complete list of packages scraped from packagist I found no packages affected by this., _(*19)

Example semantic versions which are valid but the library is unable to parse:, _(*20)

• 1.0.0-0.3.7
• 1.0.0-beta-17