Getting Started

Install via Composer:

composer require phlak/semver

Start by using the Semver class to parse, compare, and manipulate semantic versions:

use Phlak\Semver;

$version = Semver::make('1.2.3');
echo $version->major; // 1
echo $version->minor; // 2
echo $version->patch; // 3

The most common first use case: validate and compare versions (e.g., for dependency checks):

$target = Semver::make('2.0.0');
$current = Semver::make('1.9.5');

if ($current->isLessThan($target)) {
    // Require upgrade
}

Implementation Patterns

Version Bumping: Increment major/minor/patch based on semver rules:

$v = Semver::make('1.2.3-beta.1');
$v->bumpPatch(); // → 1.2.4
$v->bumpMinor(); // → 1.3.0
$v->bumpMajor(); // → 2.0.0

Constraint Checking: Validate against semver ranges:

Semver::satisfies('1.5.2', '>=1.0.0 <2.0.0'); // true

Changelog Generation: Integrate into CI/CD pipelines to auto-detect changes between tags:

$from = Semver::make('1.0.0');
$to   = Semver::make('1.2.3');
echo $to->type(); // 'minor' (or 'major', 'patch')

Laravel Integration: Use in service providers for dependency validation or package version constraints. Extend via Semver::parse() with strict mode to reject non-compliant versions.

Pre-release & Build Metadata: Non-numeric suffixes (-alpha, +build.123) are preserved and respected in comparisons. 1.0.0-alpha < 1.0.0, but 1.0.0+build == 1.0.0 in equality checks unless using isIdentical().
Strict Parsing: Use Semver::make() over parse() for safer parsing—make() throws InvalidVersionException on malformed strings.
Zero Padding: Avoid leading zeros (01.2.3)—they are treated as invalid by strict semver and will fail parsing.
Extensibility: Implement custom comparison logic via Semver::compare() with custom callbacks, or extend the class for domain-specific rules (e.g., enterprise versioning).
Caching Tip: In high-frequency scenarios (e.g., CLI tools), pre-parse versions once and reuse Semver objects—parsing is cheap, but avoid redundant calls in tight loops.