Version

Represents and manipulates versions according to the Semantic Versioning 2.0.0 specification (SemVer).

This class allows parsing a SemVer string (e.g., "1.2.3-rc.1+build.456") into its constituent parts: major, minor, patch, pre-release identifiers, and build metadata.

It provides methods to:

• Access individual version components (getMajor(), getMinor(), getPatch(), getPreRelease(), getMetadata()).
• Compare two Version objects or a Version object and a SemVer string based on SemVer precedence rules (compareTo(), equals(), lessThan(), greaterThan()).
• Conditionally update the version based on precedence (setIfHigher(), setIfLower()).

Comparison follows SemVer 2.0.0 rules:

• Major, Minor, Patch are compared numerically.
• Pre-release versions have lower precedence than normal versions (1.0.0-alpha < 1.0.0).
• Pre-release identifiers are compared segment by segment (numeric vs. alphanumeric, lexicographical).
• Build metadata is ignored during precedence comparison.

Example Usage:

use Hazaar\Util\Version;

// Create a version object
$v1 = new Version('1.2.3-beta.1+build.100');
echo $v1; // Outputs: 1.2.3-beta.1+build.100

// Access components
echo $v1->getMajor(); // Outputs: 1
echo $v1->getMinor(); // Outputs: 2
echo $v1->getPatch(); // Outputs: 3
echo $v1->getPreRelease(); // Outputs: beta.1
echo $v1->getMetadata(); // Outputs: build.100

// Compare versions
$v2 = new Version('1.2.3-beta.2');
$v3 = new Version('1.2.3');

var_dump($v1->lessThan($v2)); // bool(true) because beta.1 < beta.2
var_dump($v2->lessThan($v3)); // bool(true) because pre-release < normal release
var_dump($v1->equals('1.2.3-beta.1+build.999')); // bool(true) - metadata ignored for equality

// Conditional update
$currentVersion = new Version('2.0.0');
$currentVersion->setIfHigher('1.9.0'); // No change, 1.9.0 is not higher
echo $currentVersion; // Outputs: 2.0.0
$currentVersion->setIfHigher('2.1.0-alpha'); // Changes, 2.1.0-alpha is higher
echo $currentVersion; // Outputs: 2.1.0-alpha

Properties

version

private string $version = 'none'

major

private int $major

minor

private int $minor

patch

private int $patch

preRelease

public string $preRelease

metadata

public string $metadata

Methods

__construct

Version constructor.

public __construct(string $version): void

Parses the provided SemVer 2.0.0 version string.

Parameters

Parameter	Type	Description
$version	string	The SemVer 2.0.0 version string (e.g., "1.2.3", "2.0.0-rc.1", "1.0.0+build.123").

__toString

Magic method to output the version as a string.

public __toString(): void

Returns the original, full version string provided during construction or via set().

set

Sets the version string and updates the internal version components.

public set(string $version): void

Parses the provided SemVer 2.0.0 string and stores its components (major, minor, patch, pre-release, metadata). The original string is also stored.

Parameters

Parameter	Type	Description
$version	string	The SemVer 2.0.0 version string to set.

get

public get(): string

getMajor

Get the major version number.

public getMajor(): int

getMinor

Get the minor version number.

public getMinor(): int

getPatch

Get the patch version number.

public getPatch(): int

getPreRelease

Get the pre-release identifier string.

public getPreRelease(): ?string

Returns the pre-release part of the version string (e.g., "rc.1" in "1.2.3-rc.1+build.456"). Returns null if there is no pre-release identifier.

getMetadata

Get the build metadata string.

public getMetadata(): ?string

Returns the build metadata part of the version string (e.g., "build.456" in "1.2.3-rc.1+build.456"). Returns null if there is no build metadata.

compareTo

Compare the current version instance to another version according to SemVer 2.0.0 precedence rules.

public compareTo(Version $that): int

Comparison logic:

1. Major, Minor, Patch are compared numerically.
2. Pre-release versions have lower precedence than normal versions (e.g., 1.0.0-alpha < 1.0.0).
3. Pre-release identifiers are compared dot-separated field by field:
   • Numeric fields compared numerically.
   • Alphanumeric fields compared lexicographically (ASCII sort order).
   • Numeric fields have lower precedence than alphanumeric fields.
   • Shorter set of fields has lower precedence if all preceding fields are equal (e.g., 1.0.0-alpha < 1.0.0-alpha.1).
4. Build metadata is ignored during precedence comparison.

Returns an integer indicating the result:

• 0: Indicates the versions have the same precedence (ignoring build metadata).
• -1: Means the current version has lower precedence than $that.
• 1: Means the current version has higher precedence than $that.

Parameters

Parameter	Type	Description
$that	Version	The version to compare against. Can be either a SemVer string or another Version object.

equals

Checks if the current version is equal to another version based on SemVer precedence.

public equals(Version $that): bool

Note: This ignores build metadata as per SemVer 2.0.0 rules for precedence. Two versions differing only in build metadata are considered equal in precedence.

Parameters

Parameter	Type	Description
$that	Version	the version to compare to (string or Version object)

setIfHigher

Sets the current version instance to the given version if the given version has higher precedence.

public setIfHigher(Version $version): void

Compares the current version with the provided one using SemVer precedence rules. If the provided version is higher, the current instance is updated to match it.

Parameters

Parameter	Type	Description
$version	Version	the version to compare against and potentially set (string or Version object)

setIfLower

Sets the current version instance to the given version if the given version has lower precedence.

public setIfLower(Version $version): void

Compares the current version with the provided one using SemVer precedence rules. If the provided version is lower, the current instance is updated to match it.

Parameters

Parameter	Type	Description
$version	Version	the version to compare against and potentially set (string or Version object)

equalTo

Checks if the current version is equal to another version based on SemVer precedence.

public equalTo(Version $that): bool

Alias for equals(). Ignores build metadata.

Parameters

Parameter	Type	Description
$that	Version	the version to compare to (string or Version object)

lessThan

Checks if the current version has lower precedence than another version.

public lessThan(Version $that): bool

Compares versions based on SemVer 2.0.0 precedence rules.

Parameters

Parameter	Type	Description
$that	Version	the version to compare to (string or Version object)

greaterThan

Checks if the current version has higher precedence than another version.

public greaterThan(Version $that): bool

Compares versions based on SemVer 2.0.0 precedence rules.

Parameters

Parameter	Type	Description
$that	Version	the version to compare to (string or Version object)

---

Generated by Hazaar API Doc Generator on Tue, 06 May 2025 01:33:02 +0000