From 017c50672a177e3d20398a5470d90d8852c69663 Mon Sep 17 00:00:00 2001 From: Sebastiaan Stok Date: Fri, 13 Nov 2026 19:05:43 +0100 Subject: [PATCH] Add VersionRange value object --- composer.json | 3 +- src/VersionRange.php | 196 ++++++++++++++++++++++++ tests/VersionRangeTest.php | 298 +++++++++++++++++++++++++++++++++++++ 3 files changed, 496 insertions(+), 1 deletion(-) create mode 100644 src/VersionRange.php create mode 100644 tests/VersionRangeTest.php diff --git a/composer.json b/composer.json index fe5d8a3..a0653e6 100644 --- a/composer.json +++ b/composer.json @@ -12,7 +12,8 @@ "require": { "php": "^8.3", "symfony/polyfill-php85": "^1.43", - "symfony/polyfill-php86": "^1.34" + "symfony/polyfill-php86": "^1.34", + "composer/semver": "^3.5.2" }, "require-dev": { "phpunit/phpunit": "^12.5 || ^13.4", diff --git a/src/VersionRange.php b/src/VersionRange.php new file mode 100644 index 0000000..54ab115 --- /dev/null +++ b/src/VersionRange.php @@ -0,0 +1,196 @@ + + * + * This source file is subject to the MIT license that is bundled + * with this source code in the file LICENSE. + */ + +namespace Rollerworks\Component\Version; + +use Composer\Semver\Constraint\ConstraintInterface; +use Composer\Semver\VersionParser; + +/** + * A version range consists of a lower and upper bound (either inclusive or exclusive). + */ +final class VersionRange +{ + private static VersionParser $versionParser; + private readonly ?ConstraintInterface $constraint; + + public function __construct( + public readonly ?Version $lowerBound = null, + public readonly ?Version $upperBound = null, + public readonly bool $lowerInclusive = false, + public readonly bool $upperInclusive = false, + ) { + if ($lowerBound === null && $upperBound === null) { + $this->constraint = null; + + return; + } + + self::$versionParser ??= new VersionParser(); + $this->constraint = self::$versionParser->parseConstraints($this->__toString()); + } + + public static function createFromString(string $constraints): self + { + if ($constraints === '') { + return new self(); + } + + self::$versionParser ??= new VersionParser(); + + return self::createFromConstraint(self::$versionParser->parseConstraints($constraints)); + } + + /** + * @param (string|Version)[] $versions + */ + public static function createFromList(array $versions, bool $lowerInclusive = true, bool $upperInclusive = true): self + { + $versions = Version::createFromList($versions, sortDirection: \SortDirection::Descending); + + return new self(array_first($versions), array_last($versions), $lowerInclusive, $upperInclusive); + } + + public static function createFromConstraint(ConstraintInterface $constraint): self + { + $min = $constraint->getLowerBound(); + $max = $constraint->getUpperBound(); + + if ($min->isZero()) { + $min = null; + } + + if ($max->isPositiveInfinity()) { + $max = null; + } + + return new self( + $min ? Version::fromString($min->getVersion()) : null, + $max ? Version::fromString($max->getVersion()) : null, + $min?->isInclusive() ?? false, + $max?->isInclusive() ?? false, + ); + } + + public function isWithinRange(Version $version): bool + { + if ($this->constraint === null) { + return false; + } + + return $this->constraint->matches(self::$versionParser->parseConstraints((string) $version)); + } + + /** + * Return whether the versions cover the bounds of this VersionRange. + * + * For example a range of `>=1.0 <=3.0` requires at least one version + * covers the lower bound of `1.0` *and* another the upper bound of `3.0`. + * + * This method should only be used for specific validation purposes. + * To check if the constraints matches for a version use + * {@see VersionRange::isWithinRange()} instead. + * + * Note: + * + * Only fully inclusive VersionRanges can be checked for bounds covering. + * + * Checking the bounds of an exclusive VersionRange requires too much knowledge of + * what is considered acceptable for `<2.0`, technically less than `1.0` is + * considered acceptable, but are we looking for `1.9`, `1.99` or `1.9999999`?? + */ + public function areBoundsCoveredBy(Version ...$versions): bool + { + if (! $this->lowerInclusive || ! $this->upperInclusive) { + throw new \InvalidArgumentException('Cannnot check bounds covering unless both bounds are inclusive.'); + } + + if ($this->lowerBound === null || $this->upperBound === null) { + return false; + } + + $lowerBoundCovered = false; + $upperBoundCovered = false; + + foreach ($versions as $version) { + $lowerBoundCovered = $lowerBoundCovered ?: $this->lowerBound->equals($version); + $upperBoundCovered = $upperBoundCovered ?: $this->upperBound->equals($version); + } + + return $lowerBoundCovered && $upperBoundCovered; + } + + public function __toString(): string + { + $str = []; + + if ($this->lowerBound) { + $str[] = ($this->lowerInclusive ? '>=' : '>') . $this->lowerBound->format(); + } + + if ($this->upperBound) { + $str[] = ($this->upperInclusive ? '<=' : '<') . $this->upperBound->format(); + } + + return implode(' ', $str); + } + + /** + * Returns a normalized version range string. + * + * Note that this is to be used for display purposes only. + * Use {@see VersionRange::__toString()} instead to get a constraint string. + * + * By default pre-releases are normalized, change the format to display them fully. + * Examples without a patch/buid had that version identifier omitted at construction. + * + * Examples: + * + * * `>=1.0 =<3.0` becomes `1.0 - 3.0` + * * `>=1.0 =<3.0.0` becomes `1.0 - 3.0.0` + * * `>=1.0 =<3.0.0.5` becomes `1.0 - 3.0.0.5` + * + * For exclusive ranges, the bounds are displayed as lower/higher than. + * We cannot guess what the previous version would be. + * + * * `>0.1 <3.0.0` becomes `>0.1 - <3.0.0` + * * `>0.1 <3.0.0.0` becomes `>0.1 - <3.0.0.0` + * * `>=0.1 <3.0.0` becomes `0.1 - <3.0.0` + * * `>=0.1 <3.0.0.0` becomes `0.1 - <3.0.0.0` + * + * @param string $format the format to use for the versions + * See {@see Version::format()} for more information + */ + public function toNormalizedStr(?string $format = '{major}.{minor}.{?patch}.{?build}'): string + { + if ($this->lowerBound && $this->upperBound === null) { + return ($this->lowerInclusive ? '>=' : '>') . $this->lowerBound->format($format); + } + + if ($this->upperBound && $this->lowerBound === null) { + return ($this->upperInclusive ? '<=' : '<') . $this->upperBound->format($format); + } + + $str = []; + + if ($this->lowerBound) { + $str[] = ($this->lowerInclusive ? '' : '>') . $this->lowerBound->format($format); + } + + if ($this->upperBound) { + $str[] = ($this->upperInclusive ? '' : '<') . $this->upperBound->format($format); + } + + return implode(' - ', $str); + } +} diff --git a/tests/VersionRangeTest.php b/tests/VersionRangeTest.php new file mode 100644 index 0000000..48310f2 --- /dev/null +++ b/tests/VersionRangeTest.php @@ -0,0 +1,298 @@ + + * + * This source file is subject to the MIT license that is bundled + * with this source code in the file LICENSE. + */ + +namespace Rollerworks\Component\Version\Tests; + +use Composer\Semver\Constraint\Constraint; +use PHPUnit\Framework\Attributes\Test; +use PHPUnit\Framework\TestCase; +use Rollerworks\Component\Version\Version; +use Rollerworks\Component\Version\VersionRange; + +/** + * @internal + */ +final class VersionRangeTest extends TestCase +{ + #[Test] + public function it_creates_empty_range(): void + { + $range = VersionRange::createFromString(''); + self::assertSame('', (string) $range); + self::assertNull($range->lowerBound); + self::assertNull($range->upperBound); + self::assertFalse($range->isWithinRange(Version::create())); + + $range = new VersionRange(); + self::assertSame('', (string) $range); + self::assertNull($range->lowerBound); + self::assertNull($range->upperBound); + self::assertFalse($range->isWithinRange(Version::create())); + } + + #[Test] + public function it_creates(): void + { + $range = new VersionRange($l = Version::fromString('1.0', options: Version::INPUT_FILL_PATCH), $u = Version::fromString('2.0'), true, true); + self::assertSame('>=1.0.0 <=2.0', (string) $range); + self::assertSame($l, $range->lowerBound); + self::assertSame($u, $range->upperBound); + self::assertSame('1.0.0 - 2.0', $range->toNormalizedStr()); + + $range = new VersionRange($l = Version::fromString('1.0', options: Version::INPUT_FILL_PATCH), $u = Version::fromString('2.0'), false, false); + self::assertSame('>1.0.0 <2.0', (string) $range); + self::assertSame($l, $range->lowerBound); + self::assertSame($u, $range->upperBound); + self::assertSame('>1.0.0 - <2.0', $range->toNormalizedStr()); + + $range = new VersionRange($l = Version::fromString('1.0', outputFormat: 'v{major}.{minor}.{patch}'), $u = Version::fromString('2.0.5', outputFormat: 'v{major}.{minor}'), true, true); + self::assertSame('>=v1.0.0 <=v2.0', (string) $range); + self::assertSame($l, $range->lowerBound); + self::assertSame($u, $range->upperBound); + self::assertSame('1.0.0 - 2.0.5', $range->toNormalizedStr('{major}.{minor}.{patch}')); + } + + #[Test] + public function it_creates_from_string(): void + { + $range = VersionRange::createFromString('>1.0, <2.0'); + + self::assertSame('>1.0.0.0 <2.0.0.0', (string) $range); + self::assertSame('1.0.0.0', (string) $range->lowerBound); + self::assertSame('2.0.0.0', (string) $range->upperBound); + self::assertSame('>1.0.0.0 - <2.0.0.0', $range->toNormalizedStr()); + + $range = VersionRange::createFromString('^1.0'); + self::assertSame('>=1.0.0.0 <2.0.0.0', (string) $range); + self::assertSame('1.0.0.0', (string) $range->lowerBound); + self::assertSame('2.0.0.0', (string) $range->upperBound); + self::assertSame('1.0.0.0 - <2.0.0.0', $range->toNormalizedStr()); + } + + #[Test] + public function it_creates_from_constraint(): void + { + $range = VersionRange::createFromConstraint(new Constraint(Constraint::STR_OP_GT, '1.0')); + self::assertSame('1.0', (string) $range->lowerBound); + self::assertNull($range->upperBound); + self::assertFalse($range->lowerInclusive); + self::assertFalse($range->upperInclusive); + self::assertSame('>1.0', (string) $range); + self::assertSame('>1.0', $range->toNormalizedStr()); + + $range = VersionRange::createFromConstraint(new Constraint(Constraint::STR_OP_LT, '1.0')); + self::assertNull($range->lowerBound); + self::assertSame('1.0', (string) $range->upperBound); + self::assertFalse($range->lowerInclusive); + self::assertFalse($range->upperInclusive); + self::assertSame('<1.0', (string) $range); + self::assertSame('<1.0', $range->toNormalizedStr()); + + $range = VersionRange::createFromConstraint(new Constraint(Constraint::STR_OP_GE, '1.0')); + self::assertSame('1.0', (string) $range->lowerBound); + self::assertNull($range->upperBound); + self::assertTrue($range->lowerInclusive); + self::assertFalse($range->upperInclusive); + self::assertSame('>=1.0', (string) $range); + self::assertSame('>=1.0', $range->toNormalizedStr()); + + $range = VersionRange::createFromConstraint(new Constraint(Constraint::STR_OP_LE, '1.0')); + self::assertNull($range->lowerBound); + self::assertSame('1.0', (string) $range->upperBound); + self::assertFalse($range->lowerInclusive); + self::assertTrue($range->upperInclusive); + self::assertSame('<=1.0', (string) $range); + self::assertSame('<=1.0', $range->toNormalizedStr()); + } + + #[Test] + public function it_checks_whether_is_within_range(): void + { + $range = VersionRange::createFromString('>=1.0, <2.0'); + self::assertTrue($range->isWithinRange(Version::fromString('1.0.0.0'))); + self::assertTrue($range->isWithinRange(Version::fromString('1.0.0.1'))); + self::assertTrue($range->isWithinRange(Version::fromString('1.9.9.9'))); + self::assertFalse($range->isWithinRange(Version::fromString('0.9.9.9'))); + self::assertFalse($range->isWithinRange(Version::fromString('2.0.0.0'))); + + $range = VersionRange::createFromString('>=1.0, <=2.0'); + self::assertTrue($range->isWithinRange(Version::fromString('1.0.0.0'))); + self::assertTrue($range->isWithinRange(Version::fromString('1.0.0.1'))); + self::assertTrue($range->isWithinRange(Version::fromString('1.9.9.9'))); + self::assertTrue($range->isWithinRange(Version::fromString('2.0.0.0'))); + self::assertFalse($range->isWithinRange(Version::fromString('0.9.9.9'))); + + $range = VersionRange::createFromString('^0.3'); + self::assertTrue($range->isWithinRange(Version::fromString('0.3.0.0'))); + self::assertTrue($range->isWithinRange(Version::fromString('0.3.0.1'))); + self::assertTrue($range->isWithinRange(Version::fromString('0.3.9.9'))); + self::assertFalse($range->isWithinRange(Version::fromString('0.2.9.9'))); + self::assertFalse($range->isWithinRange(Version::fromString('0.4.0.0'))); + } + + #[Test] + public function it_creates_from_list(): void + { + $range = VersionRange::createFromList([ + $lower = Version::fromString('1.0.0.0'), + $upper = Version::fromString('1.9.0.0'), + Version::fromString('1.0.0.1'), + Version::fromString('1.5.0.1'), + ]); + self::assertEquals($lower, $range->lowerBound); + self::assertEquals($upper, $range->upperBound); + self::assertSame('>=1.0.0.0 <=1.9.0.0', (string) $range); + + $range = VersionRange::createFromList( + [ + $lower = Version::fromString('1.0.0.0'), + $upper = Version::fromString('1.9.0.0'), + Version::fromString('1.0.0.1'), + Version::fromString('1.3.7.1'), + ], + lowerInclusive: false, + upperInclusive: false, + ); + self::assertEquals($lower, $range->lowerBound); + self::assertEquals($upper, $range->upperBound); + self::assertSame('>1.0.0.0 <1.9.0.0', (string) $range); + + $range = VersionRange::createFromList( + [ + $lower = Version::fromString('1.0.0.0'), + $upper = Version::fromString('1.9.0.0'), + Version::fromString('1.0.0.1'), + Version::fromString('1.3.7.1'), + ], + upperInclusive: false, + ); + self::assertEquals($lower, $range->lowerBound); + self::assertEquals($upper, $range->upperBound); + self::assertSame('>=1.0.0.0 <1.9.0.0', (string) $range); + + $range = VersionRange::createFromList( + [ + $lower = Version::fromString('1.0.0.0'), + $upper = Version::fromString('1.9.0.0'), + Version::fromString('1.0.0.1'), + Version::fromString('1.3.7.1'), + ], + lowerInclusive: false, + ); + self::assertEquals($lower, $range->lowerBound); + self::assertEquals($upper, $range->upperBound); + self::assertSame('>1.0.0.0 <=1.9.0.0', (string) $range); + } + + #[Test] + public function it_checks_bounds_coverage(): void + { + $range = new VersionRange(Version::fromString('8.3'), Version::fromString('8.5'), true, true); + + self::assertTrue( + $range->areBoundsCoveredBy( + Version::fromString('8.0'), + Version::fromString('8.3'), + Version::fromString('8.5'), + Version::fromString('8.6'), + ) + ); + + self::assertFalse( + $range->areBoundsCoveredBy( + Version::fromString('8.1'), + Version::fromString('8.4'), + ) + ); + + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.3'))); + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.5'))); + } + + #[Test] + public function it_gives_false_for_bounds_coverage_with_only_one_bound(): void + { + $range = new VersionRange(Version::fromString('8.3'), lowerInclusive: true, upperInclusive: true); + self::assertFalse( + $range->areBoundsCoveredBy( + Version::fromString('8.0'), + Version::fromString('8.3'), + Version::fromString('8.5'), + Version::fromString('8.6'), + ) + ); + + self::assertFalse( + $range->areBoundsCoveredBy( + Version::fromString('8.1'), + Version::fromString('8.4'), + ) + ); + + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.3'))); + + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.5'))); + + $range = new VersionRange(upperBound: Version::fromString('8.3'), lowerInclusive: true, upperInclusive: true); + self::assertFalse( + $range->areBoundsCoveredBy( + Version::fromString('8.0'), + Version::fromString('8.3'), + Version::fromString('8.5'), + Version::fromString('8.6'), + ) + ); + + self::assertFalse( + $range->areBoundsCoveredBy( + Version::fromString('8.1'), + Version::fromString('8.4'), + ) + ); + + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.3'))); + self::assertFalse($range->areBoundsCoveredBy(Version::fromString('8.5'))); + } + + #[Test] + public function it_cannot_check_exclusive_bounds_for_coverage_lower(): void + { + $range = new VersionRange(Version::fromString('8.3'), Version::fromString('8.5'), false, true); + + $this->expectException(\InvalidArgumentException::class); + $this->expectExceptionMessageContains('Cannnot check bounds covering unless both bounds are inclusive.'); + + $range->areBoundsCoveredBy(Version::fromString('8.0')); + } + + #[Test] + public function it_cannot_check_exclusive_bounds_for_coverage_upper(): void + { + $range = new VersionRange(Version::fromString('8.3'), Version::fromString('8.5'), true, false); + + $this->expectException(\InvalidArgumentException::class); + $this->expectExceptionMessageContains('Cannnot check bounds covering unless both bounds are inclusive.'); + + $range->areBoundsCoveredBy(Version::fromString('8.0')); + } + + private function expectExceptionMessageContains(string $message): void + { + /** @phpstan-ignore-next-line PHPUnit forward compatibility */ + if (method_exists($this, 'expectExceptionMessageIsOrContains')) { + $this->expectExceptionMessageIsOrContains($message); + } else { + $this->expectExceptionMessage($message); + } + } +}