Enhancement: Allow comparing Versions

.github/workflows/integrate.yaml

@@ -59,7 +59,7 @@ jobs:
           dependencies: "${{ matrix.dependencies }}"
 
       - name: "Run backward-compatibility analysis with roave/backward-compatibility-check"
-        run: "vendor/bin/roave-backward-compatibility-check --ansi --format=github-actions --from=421ce5b"
+        run: "vendor/bin/roave-backward-compatibility-check --ansi --format=github-actions --from=43b3334"
 
   code-coverage:
     name: "Code Coverage"

Makefile

@@ -3,7 +3,7 @@ it: refactoring coding-standards security-analysis static-code-analysis tests ##
 
 .PHONY: backward-compatibility-analysis
 backward-compatibility-analysis: vendor ## Runs a backward-compatibility analysis with roave/backward-compatibility-check
-	vendor/bin/roave-backward-compatibility-check --from=421ce5b
+	vendor/bin/roave-backward-compatibility-check --from=43b3334
 
 .PHONY: code-coverage
 code-coverage: vendor ## Collects coverage from running unit tests with phpunit/phpunit

README.md

@@ -125,12 +125,13 @@ declare(strict_types=1);
 
 use Ergebnis\Version;
 
-$one = Version\Version::fromString('1.2.3');
+$one = Version\Version::fromString('1.2.3-alpha');
 $two = Version\Version::fromString('1.2.3');
-$three = Version\Version::fromString('1.2.4');
+$three = Version\Version::fromString('1.2.4+build.9001');
 
-$one->equals($two); // true
-$one->equals($three); // false
+$one->compare($two); // -1
+$one->compare($one); // 0
+$three->compare($one); // 1
 ```
 
 ### Create a `Major` from an `int`

psalm-baseline.xml

@@ -30,12 +30,34 @@
     </PossiblyUnusedMethod>
   </file>
   <file src="test/DataProvider/VersionProvider.php">
+    <InvalidArrayOffset>
+      <code>$valuesWithBuildMetaData[$i]</code>
+      <code>$valuesWithBuildMetaData[$j]</code>
+    </InvalidArrayOffset>
+    <InvalidDocblock>
+      <code>public static function valuesWhereFirstValueIsEqualToSecondValue(): \Generator</code>
+    </InvalidDocblock>
+    <InvalidReturnType>
+      <code><![CDATA[\Generator<string, array{0: string, 1: string}>]]></code>
+      <code><![CDATA[\Generator<string, array{0: string, 1: string}>]]></code>
+    </InvalidReturnType>
+    <MixedArgument>
+      <code>$otherValue</code>
+      <code>$value</code>
+    </MixedArgument>
+    <MixedAssignment>
+      <code>$otherValue</code>
+      <code>$value</code>
+    </MixedAssignment>
     <PossiblyUnusedMethod>
       <code>invalid</code>
       <code>valid</code>
       <code>valueAndValueWithBumpedMajor</code>
       <code>valueAndValueWithBumpedMinor</code>
       <code>valueAndValueWithBumpedPatch</code>
+      <code>valuesWhereFirstValueIsEqualToSecondValue</code>
+      <code>valuesWhereFirstValueIsGreaterThanSecondValue</code>
+      <code>valuesWhereFirstValueIsSmallerThanSecondValue</code>
     </PossiblyUnusedMethod>
   </file>
   <file src="test/Unit/BuildMetaDataTest.php">

src/Version.php

@@ -145,9 +145,45 @@ public function bumpPatch(): self
         );
     }
 
-    public function equals(self $other): bool
+    public function compare(self $other): int
     {
-        return $this->toString() === $other->toString();
+        $major = $this->major->compare($other->major);
+
+        if (0 !== $major) {
+            return $major;
+        }
+
+        $minor = $this->minor->compare($other->minor);
+
+        if (0 !== $minor) {
+            return $minor;
+        }
+
+        $patch = $this->patch->compare($other->patch);
+
+        if (0 !== $patch) {
+            return $patch;
+        }
+
+        if ($this->preRelease->equals(PreRelease::empty())) {
+            if ($other->preRelease->equals(PreRelease::empty())) {
+                return 0;
+            }
+
+            return 1;
+        }
+
+        if ($other->preRelease->equals(PreRelease::empty())) {
+            return -1;
+        }
+
+        $preRelease = $this->preRelease->compare($other->preRelease);
+
+        if (0 !== $preRelease) {
+            return $preRelease;
+        }
+
+        return 0;
     }
 
     public function major(): Major

test/DataProvider/VersionProvider.php

@@ -199,4 +199,163 @@ public static function valueAndValueWithBumpedPatch(): \Generator
             ];
         }
     }
+
+    /**
+     * @return \Generator<string, array{0: string, 1: string}>
+     */
+    public static function valuesWhereFirstValueIsSmallerThanSecondValue(): \Generator
+    {
+        $values = self::valuesOrderedByPrecedence();
+
+        $count = \count($values);
+
+        for ($i = 0; $count - 1 > $i; ++$i) {
+            $value = $values[$i];
+
+            for ($j = $i + 1; $count > $j; ++$j) {
+                $otherValue = $values[$j];
+
+                $key = \sprintf(
+                    '%s-smaller-than-%s',
+                    $value,
+                    $otherValue,
+                );
+
+                yield $key => [
+                    $value,
+                    $otherValue,
+                    -1,
+                ];
+            }
+        }
+    }
+
+    /**
+     * @return \Generator<string, array{0: string, 1: string}>
+     */
+    public static function valuesWhereFirstValueIsGreaterThanSecondValue(): \Generator
+    {
+        $values = \array_reverse(self::valuesOrderedByPrecedence());
+
+        $count = \count($values);
+
+        for ($i = 0; $count - 1 > $i; ++$i) {
+            $value = $values[$i];
+
+            for ($j = $i + 1; $count > $j; ++$j) {
+                $otherValue = $values[$j];
+
+                $key = \sprintf(
+                    '%s-greater-than-%s',
+                    $value,
+                    $otherValue,
+                );
+
+                yield $key => [
+                    $value,
+                    $otherValue,
+                    -1,
+                ];
+            }
+        }
+    }
+
+    /**
+     * @see https://semver.org/#spec-item-11
+     * @see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+     * @see https://regex101.com/r/Ly7O1x/3/
+     *
+     * @return \Generator<string, array{0: string, 1: string}
+     */
+    public static function valuesWhereFirstValueIsEqualToSecondValue(): \Generator
+    {
+        $values = [
+            [
+                '1.0.0',
+                '1.0.0+0.build.1-rc.10000aaa-kk-0.1',
+            ],
+            [
+                '1.0.0-rc.1',
+                '1.0.0-rc.1+build.1',
+                '1.0.0-rc.1+build.9000',
+            ],
+            [
+                '1.1.2',
+                '1.1.2+meta',
+                '1.1.2+meta-valid',
+            ],
+            [
+                '1.2.3----RC-SNAPSHOT.12.9.1--.12',
+                '1.2.3----RC-SNAPSHOT.12.9.1--.12+788',
+            ],
+            [
+                '2.0.0',
+                '2.0.0+build.1848',
+            ],
+        ];
+
+        foreach ($values as $valuesWithBuildMetaData) {
+            $count = \count($valuesWithBuildMetaData);
+
+            for ($i = 0; $count - 1 > $i; ++$i) {
+                $value = $valuesWithBuildMetaData[$i];
+
+                for ($j = $i + 1; $j < $count; ++$j) {
+                    $otherValue = $valuesWithBuildMetaData[$j];
+
+                    $key = \sprintf(
+                        '%s-equal-to-%s',
+                        $value,
+                        $otherValue,
+                    );
+
+                    yield $key => [
+                        $value,
+                        $otherValue,
+                        -1,
+                    ];
+                }
+            }
+        }
+    }
+
+    /**
+     * @see https://semver.org/#spec-item-11
+     * @see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+     * @see https://regex101.com/r/Ly7O1x/3/
+     * @see https://www.sfu.ca/sasdoc/sashtml/proc/z1epts.htm
+     *
+     * @return list<string>
+     */
+    private static function valuesOrderedByPrecedence(): array
+    {
+        return [
+            '0.0.4',
+            '1.0.0-0A.is.legal',
+            '1.0.0-alpha',
+            '1.0.0-alpha.1',
+            '1.0.0-alpha.0valid',
+            '1.0.0-alpha.beta',
+            '1.0.0-alpha.beta.1',
+            '1.0.0-alpha-a.b-c-somethinglong+build.1-aef.1-its-okay',
+            '1.0.0-alpha0.valid',
+            '1.0.0-beta',
+            '1.0.0-rc.1+build.1',
+            '1.0.0',
+            '1.1.2-prerelease+meta',
+            '1.1.2+meta',
+            '1.1.7',
+            '1.2.3----R-S.12.9.1--.12',
+            '1.2.3----RC-SNAPSHOT.12.9.1--.12',
+            '1.2.3-SNAPSHOT-123',
+            '1.2.3-beta',
+            '1.2.3',
+            '2.0.0-rc.1+build.123',
+            '2.0.0',
+            '2.0.1-alpha.1227',
+            '10.2.3-DEV-SNAPSHOT',
+            '10.20.30',
+            '99999999999999999999999.999999999999999999.99999999999999999',
+        ];
+    }
 }

test/Unit/VersionTest.php

@@ -347,23 +347,45 @@ public function testBumpPatchReturnsVersionWithBumpedPatch(
         self::assertSame($valueWithBumpedPatch, $two->toString());
     }
 
-    public function testEqualsReturnsFalseWhenValuesAreDifferent(): void
-    {
-        $faker = self::faker()->unique();
-
-        $one = Version::fromString($faker->regexify('(0|[1-9]+)\.(0|[1-9]+)\.(0|[1-9]+)'));
-        $two = Version::fromString($faker->regexify('(0|[1-9]+)\.(0|[1-9]+)\.(0|[1-9]+)'));
+    #[Framework\Attributes\DataProviderExternal(Test\DataProvider\VersionProvider::class, 'valuesWhereFirstValueIsSmallerThanSecondValue')]
+    public function testCompareReturnsMinusOneWhenFirstValueIsSmallerThanSecondValue(
+        string $firstValue,
+        string $secondValue,
+    ): void {
+        $one = Version::fromString($firstValue);
+        $two = Version::fromString($secondValue);
 
-        self::assertFalse($one->equals($two));
+        self::assertSame(-1, $one->compare($two));
     }
 
-    public function testEqualsReturnsTrueWhenValueIsSame(): void
+    #[Framework\Attributes\DataProviderExternal(Test\DataProvider\VersionProvider::class, 'valid')]
+    public function testCompareReturnsZeroWhenFirstValueIsIdenticalToSecondValue(string $value): void
     {
-        $value = self::faker()->regexify('(0|[1-9]+)\.(0|[1-9]+)\.(0|[1-9]+)');
-
         $one = Version::fromString($value);
         $two = Version::fromString($value);
 
-        self::assertTrue($one->equals($two));
+        self::assertSame(0, $one->compare($two));
+    }
+
+    #[Framework\Attributes\DataProviderExternal(Test\DataProvider\VersionProvider::class, 'valuesWhereFirstValueIsEqualToSecondValue')]
+    public function testCompareReturnsZeroWhenFirstValueIsEqualToSecondValue(
+        string $firstValue,
+        string $secondValue,
+    ): void {
+        $one = Version::fromString($firstValue);
+        $two = Version::fromString($secondValue);
+
+        self::assertSame(0, $one->compare($two));
+    }
+
+    #[Framework\Attributes\DataProviderExternal(Test\DataProvider\VersionProvider::class, 'valuesWhereFirstValueIsGreaterThanSecondValue')]
+    public function testCompareReturnsMinusOneWhenFirstValueIsGreaterThanSecondValue(
+        string $firstValue,
+        string $secondValue,
+    ): void {
+        $one = Version::fromString($firstValue);
+        $two = Version::fromString($secondValue);
+
+        self::assertSame(1, $one->compare($two));
     }
 }