PHP Version

A simple yet powerful library for parsing, validating, comparing, and manipulating semantic version strings in PHP. It also includes flexible support for version constraints (e.g., ^1.2.3, >=1.0.0 <2.0.0) to check whether a particular version satisfies one or more complex conditions.

Installation

composer require gregpriday/php-version

Overview

This library offers:

• Strict or Loose Parsing of version strings (e.g. "1.2.3", "v1.2.3", "1.2", "1").
• Version Object to access and modify version components (major, minor, patch, pre-release, and build metadata).
• SemVer Checks to see if a version is stable or a pre-release.
• Version Bumping/Lowering (increment/decrement major, minor, patch) including preserving or clearing pre-release/build metadata.
• Constraint Parsing and Evaluation using a fluent, chainable syntax with logical AND and OR conditions.

Basic Usage Example

Below is a quick snapshot of how you might use the library to parse a version, check its properties, bump the version, and validate it against constraints.

use GregPriday\Version\Version;
use GregPriday\Version\Constraint\VersionConstraintParser;

// 1. Create a version object (strict mode by default).
$version = new Version('1.2.3-beta');

// 2. Inspect the version
echo "Major: " . $version->getMajor() . "\n";       // 1
echo "Minor: " . $version->getMinor() . "\n";       // 2
echo "Patch: " . $version->getPatch() . "\n";       // 3
echo "Pre-release: " . $version->getPreRelease() . "\n"; // beta

// 3. Check stability
if ($version->isStable()) {
    echo "Version is stable.\n";
} else {
    echo "Version is not stable.\n";
}

// 4. Bump the version (bump minor, reset patch to 0, remove pre-release)
$bumped = $version->bumpMinor();
echo "Bumped Version: " . $bumped->getExtraInfo()['version'] . "\n"; // "1.3.0"

// 5. Parse constraints and check if a version satisfies them
$parser = new VersionConstraintParser();
$rangeSet = $parser->parseConstraints('>=1.0.0 <2.0.0 || ^3.0.0');

if ($rangeSet->isSatisfiedBy($bumped)) {
    echo $bumped->getExtraInfo()['version']." satisfies the constraint.\n";
} else {
    echo $bumped->getExtraInfo()['version']." does not satisfy the constraint.\n";
}

---

Creating and Inspecting Versions

Strict vs. Loose Parsing

• Strict mode (default): Expects full major.minor.patch (optionally -preRelease and/or +buildMetadata). Examples of valid strict versions:
  • 1.0.0
  • 0.9.5-alpha+build.1
• Loose mode: More lenient. Accepts shorter forms and can include a leading v. Examples of acceptable loose versions:
  • v1.2.3
  • 1.2 (interpreted as 1.2.0)
  • 1 (interpreted as 1.0.0)

// Strict mode (throws InvalidArgumentException if invalid)
$strictVersion = new Version('1.2.3'); 

// Loose mode
$looseVersion = new Version('v1.2', null, false);
// Internally becomes 1.2.0

Accessing Components

$version = new Version('1.2.3-alpha+build.123');

// Basic components
echo $version->getMajor();      // 1
echo $version->getMinor();      // 2
echo $version->getPatch();      // 3

// Pre-release and build metadata
echo $version->getPreRelease();    // alpha
echo $version->getBuildMetadata(); // build.123

// Extra info array (includes stability check)
$info = $version->getExtraInfo();
print_r($info);
/*
Array
(
    [version] => 1.2.3-alpha+build.123
    [major] => 1
    [minor] => 2
    [patch] => 3
    [pre_release] => alpha
    [build_metadata] => build.123
    [is_stable] => 
)
*/

Stability and Pre-Release Checks

$version = new Version('1.0.0-rc1');
if ($version->isStable()) {
    // Major >= 1 and no pre-release
    echo "Stable release.\n";
} else {
    echo "Not stable.\n"; // This will run in this example
}

if ($version->isPreRelease()) {
    echo "It's a pre-release!\n"; // True for "1.0.0-rc1"
}

---

Bumping and Lowering Version Numbers

The VersionBumpingTrait gives you methods to increment or decrement specific parts of a version. Each method returns a new Version instance. By default, these operations clear pre-release and build metadata, but you can preserve them if you wish.

Bumping (Incrementing)

$version = new Version('1.2.3-beta+build.123');

// Bump Major: becomes 2.0.0 (clears pre-release & build by default)
$bumpedMajor = $version->bumpMajor();
echo $bumpedMajor->getExtraInfo()['version']; // 2.0.0

// Bump Minor but preserve pre-release and build metadata
$bumpedMinor = $version->bumpMinor(true, true);
echo $bumpedMinor->getExtraInfo()['version']; // 1.3.0-beta+build.123

// Bump Patch: 1.2.4 (default clears pre-release and build)
$bumpedPatch = $version->bumpPatch();
echo $bumpedPatch->getExtraInfo()['version']; // 1.2.4

// Bump (or set) Pre-release: 
// - If no pre-release, sets the given identifier. 
// - If pre-release is something like "beta.1", it increments the last number.
$newPre = $version->bumpPreRelease('alpha', true);
echo $newPre->getExtraInfo()['version']; // "1.2.3-beta.1+build.123"

Lowering (Decrementing)

You can similarly reduce major, minor, or patch. By default, these also clear pre-release/build metadata, unless you preserve them.

$version = new Version('2.3.4-beta+build.456');

// Lower Major, resetting minor/patch, discarding pre-release/build
$loweredMajor = $version->lowerMajor(true, true);
echo $loweredMajor->getExtraInfo()['version']; // "1.0.0"

// Lower Minor, preserving pre-release
$loweredMinor = $version->lowerMinor(false, true);
echo $loweredMinor->getExtraInfo()['version']; // "2.2.4-beta"

// Lower Patch, preserving build metadata
$loweredPatch = $version->lowerPatch(false, true);
echo $loweredPatch->getExtraInfo()['version']; // "2.3.3+build.456"

Note: Lowering a 0 major/minor/patch throws an exception, since negative version segments are invalid.

---

Parsing and Evaluating Constraints

The library can parse powerful OR and AND constraints using the VersionConstraintParser. This enables checks such as >=1.0.0 <2.0.0 || ^3.0.0.

Operators

• Basic: >, >=, <, <=, =, ==, !, !=
• Caret ^: e.g. ^1.2.3 means >=1.2.3 and <2.0.0 (for 1.x versions)
• Tilde ~: e.g. ~1.2.3 means >=1.2.3 and <1.3.0

Combining Constraints

• AND: Use space or commas. For example:
  >=1.0.0 <2.0.0
>=1.0.0, <2.0.0
  This means the version must satisfy both constraints.
• OR: Split with ||. For example:
  ^1.0.0 || ^2.0.0
  Means the version must satisfy either ^1.0.0 or ^2.0.0.

Example: Parsing Constraints

use GregPriday\Version\Constraint\VersionConstraintParser;
use GregPriday\Version\Version;

$parser = new VersionConstraintParser();

// Single constraint
$rangeSet = $parser->parseConstraints('>=1.2.3');
var_dump($rangeSet->isSatisfiedBy(new Version('1.2.3'))); // true
var_dump($rangeSet->isSatisfiedBy(new Version('1.2.2'))); // false

// Multiple (AND) constraints
$rangeSet = $parser->parseConstraints('>=1.0.0 <2.0.0');
// This means: version >= 1.0.0 AND version < 2.0.0
var_dump($rangeSet->isSatisfiedBy(new Version('1.5.0'))); // true
var_dump($rangeSet->isSatisfiedBy(new Version('2.1.0'))); // false

// OR constraints
$rangeSet = $parser->parseConstraints('^1.0.0 || ~2.0.0');
// This means: (version in ^1.0.0) OR (version in ~2.0.0)
// ^1.0.0 = >=1.0.0 <2.0.0
// ~2.0.0 = >=2.0.0 <2.1.0
var_dump($rangeSet->isSatisfiedBy(new Version('1.9.9'))); // true
var_dump($rangeSet->isSatisfiedBy(new Version('2.0.5'))); // true
var_dump($rangeSet->isSatisfiedBy(new Version('2.1.0'))); // false

// Negation examples
$rangeSet = $parser->parseConstraints('!=1.0.0');
var_dump($rangeSet->isSatisfiedBy(new Version('1.0.0'))); // false
var_dump($rangeSet->isSatisfiedBy(new Version('1.0.1'))); // true

---

Testing

To run the test suite, clone this repository (or have it locally) and install dev dependencies:

composer install

Then run:

vendor/bin/phpunit

This runs the PHPUnit tests under tests/.

Code Formatting

A Laravel Pint configuration is included for formatting. To format the code:

composer format

---

License

This project is open source under the MIT license.