Version Laravel Package

Getting Started

Install via composer require phar-io/version (or --dev for tooling). Begin with the two core classes: PharIo\Version\Version for parsing version strings (e.g., new Version('2.1.3-beta1')) and PharIo\Version\VersionConstraintParser for parsing constraint strings (e.g., ^8.1, ~3.2.0, >=7.4,<8.0). The most common first use case is enforcing PHP version requirements at application entry points — especially in PHARs or CLI tools — by checking compatibility with PHP_VERSION:

use PharIo\Version\Version;
use PharIo\Version\VersionConstraintParser;

$parser = new VersionConstraintParser();
$constraint = $parser->parse('^8.1');
if (! $constraint->complies(new Version(PHP_VERSION))) {
    fwrite(STDERR, 'This tool requires PHP ^8.1'.PHP_EOL);
    exit(1);
}

Implementation Patterns

• Bootstrap Validation: Add version checks early in bootstrap/app.php or console command providers to fail fast if requirements aren’t met.
• Plugin System Enforcement: When loading plugins (e.g., via composer.json extra.plugins), parse each plugin’s declared requirement (e.g., "require": {"php": "^8.0"}) using VersionConstraintParser, then verify against the host app’s version before autoloading.
• Constraint Aggregation: Use comma-separated constraints (e.g., ^8.0,<9.0) or manually combine via AndVersionConstraint to express complex policies — e.g., '^8.0, !*dev' to allow only stable 8.x releases.
• Pre-release Filtering: In preview update channels, use Version::hasPreReleaseSuffix() and isGreaterThan() to compare pre-release versions (e.g., 3.0.0-beta2 > 3.0.0-alpha3) and surface appropriate upgrade paths.
• Build Metadata Handling: Leverage equals() (added in v3.2.0) to compare versions with build metadata (e.g., 1.2.3+build.42), though remember it’s ignored for range constraints (^1.2.3 matches 1.2.3+build.any).
• Test Suites: In PHPUnit tests, assert version compatibility using Version + constraint objects — ideal for testing dependency version guards without mocking or external process calls.

Gotchas and Tips

• v Prefix: Parsed but stripped internally (new Version('v1.0.0') → '1.0.0'). Use getOriginalString() if you need to preserve it for logs/UI.
• Pre-release Rank: Pre-releases sort below the final release (e.g., 3.0.0 > 3.0.0-rc1), and suffixes like beta, alpha, dev must be lowercase — uppercase fails in comparisons (fixed in v3.0.4, but old tests may break).
• Tilde Quirk: ~1.2 behaves identically to ^1.2 (i.e., <2.0.0), not <1.3.0. Only ~1.2.3 restricts to patch-level versions (<1.3.0).
• Major-Only Syntax: Constraints like ^6 (no minor/patch) are now supported (v3.3.0+) and expanded to ^6.0.0 internally.
• OR Constraints: Single | is not supported. Logical OR must be represented via multiple top-level constraints — not via VersionConstraintParser directly. Workaround: parse constraints separately and implement OrVersionConstraint manually (or use Composer’s * wildcard and custom logic).
• Strict Type Safety: Since v3.0+, the library uses strict typing — ensure all inputs are typed or cast correctly (e.g., Version::getVersionString() returns string, not null).