add ability to compare based on semantic types

PHLAK · Sep 19, 2024 · b45bb43 · b45bb43
1 parent 22437c7
commit b45bb43
Show file tree

Hide file tree

Showing 6 changed files with 274 additions and 19 deletions.
diff --git a/.github/workflows/test-suite.yaml b/.github/workflows/test-suite.yaml
@@ -36,7 +36,7 @@ jobs:
 
     strategy:
       matrix:
-        php-versions: ['8.0', '8.1', '8.2', '8.3']
+        php-versions: ['8.1', '8.2', '8.3']
 
     steps:
       - name: Checkout Repository

diff --git a/README.md b/README.md
@@ -113,7 +113,7 @@ $version->isPreRelease();
 $version->hasBuild();
 ```
 
-#### Compare two SemVer objects
+#### Compare two SemVer objects (FULL - Compares the full version string)
 
 ```php
 $version1 = new SemVer\Version('v1.2.3');
@@ -126,6 +126,60 @@ $version1->neq($version2); // true
 $version1->gte($version2); // false
 $version1->lte($version2); // true
 ```
+##### Explicitly compare two versions using `Compare::FULL` 
+```php
+$version1 = new SemVer\Version('v1.2.3');
+$version2 = new SemVer\Version('v3.2.1');
+
+$version1->gt($version2, Compare::FULL);  // false
+$version1->lt($version2, Compare::FULL);  // true
+$version1->eq($version2, Compare::FULL);  // false
+$version1->neq($version2, Compare::FULL); // true
+$version1->gte($version2, Compare::FULL); // false
+$version1->lte($version2, Compare::FULL); // true
+```
+
+#### MAJOR - Limit the comparison to the major version only, ignores the minor, patch and pre-release versions completely
+
+```php
+$version1 = new SemVer\Version('v1.2.3-alpha.4');
+$version2 = new SemVer\Version('v1.3.4-alpha.5');
+
+$version1->gt($version2, Compare::MAJOR);  // false
+$version1->lt($version2, Compare::MAJOR);  // false
+$version1->eq($version2, Compare::MAJOR);  // true
+$version1->neq($version2, Compare::MAJOR); // false
+$version1->gte($version2, Compare::MAJOR); // true
+$version1->lte($version2, Compare::MAJOR); // true
+```
+
+#### MINOR - Limit the comparison to the major and minor versions only, ignores the patch and pre-release versions completely
+
+```php
+$version1 = new SemVer\Version('v1.2.3-alpha.4');
+$version2 = new SemVer\Version('v1.2.4-alpha.5');
+
+$version1->gt($version2, Compare::MINOR);  // false
+$version1->lt($version2, Compare::MINOR);  // false
+$version1->eq($version2, Compare::MINOR);  // true
+$version1->neq($version2, Compare::MINOR); // false
+$version1->gte($version2, Compare::MINOR); // true
+$version1->lte($version2, Compare::MINOR); // true
+```
+
+#### PATCH - Limit the comparison to the major, minor and patch versions only, ignores the pre-release version completely
+
+```php
+$version1 = new SemVer\Version('v1.2.3-alpha.4');
+$version2 = new SemVer\Version('v1.2.3-alpha.5');
+
+$version1->gt($version2, Compare::PATCH);  // false
+$version1->lt($version2, Compare::PATCH);  // false
+$version1->eq($version2, Compare::PATCH);  // true
+$version1->neq($version2, Compare::PATCH); // false
+$version1->gte($version2, Compare::PATCH); // true
+$version1->lte($version2, Compare::PATCH); // true
+```
 
 Troubleshooting
 ---------------

diff --git a/composer.json b/composer.json
@@ -23,7 +23,7 @@
         "issues": "https://github.com/PHLAK/SemVer/issues"
     },
     "require": {
-        "php": "^8.0 || ^8.1 || ^8.2 || 8.3"
+        "php": "^8.1 || ^8.2 || ^8.3"
     },
     "require-dev": {
         "phlak/coding-standards": "^2.0",

diff --git a/src/Enums/Compare.php b/src/Enums/Compare.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace PHLAK\SemVer\Enums;
+
+enum Compare
+{
+    case FULL;
+    case MAJOR;
+    case MINOR;
+    case PATCH;
+}
diff --git a/src/Traits/Comparable.php b/src/Traits/Comparable.php
@@ -2,6 +2,7 @@
 
 namespace PHLAK\SemVer\Traits;
 
+use PHLAK\SemVer\Enums\Compare;
 use PHLAK\SemVer\Version;
 
 trait Comparable
@@ -13,14 +14,17 @@ trait Comparable
      * @param Version $version1 An instance of SemVer/Version
      * @param Version $version2 An instance of SemVer/Version
      */
-    public static function compare(Version $version1, Version $version2): int
+    public static function compare(Version $version1, Version $version2, Compare $comparison = Compare::FULL): int
     {
-        $v1 = [$version1->major, $version1->minor, $version1->patch];
-        $v2 = [$version2->major, $version2->minor, $version2->patch];
+        [$v1, $v2] = match ($comparison) {
+            Compare::MAJOR => [[$version1->major], [$version2->major]],
+            Compare::MINOR => [[$version1->major, $version1->minor], [$version2->major, $version2->minor]],
+            default => [[$version1->major, $version1->minor, $version1->patch], [$version2->major, $version2->minor, $version2->patch]]
+        };
 
         $baseComparison = $v1 <=> $v2;
 
-        if ($baseComparison !== 0) {
+        if ($baseComparison !== 0 || $comparison !== Compare::FULL) {
             return $baseComparison;
         }
 
@@ -49,9 +53,9 @@ public static function compare(Version $version1, Version $version2): int
      * @return bool True if this Version object is greater than the comparing
      *              object, otherwise false
      */
-    public function gt(Version $version): bool
+    public function gt(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) > 0;
+        return self::compare($this, $version, $comparison) > 0;
     }
 
     /**
@@ -62,9 +66,9 @@ public function gt(Version $version): bool
      * @return bool True if this Version object is less than the comparing
      *              object, otherwise false
      */
-    public function lt(Version $version): bool
+    public function lt(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) < 0;
+        return self::compare($this, $version, $comparison) < 0;
     }
 
     /**
@@ -75,9 +79,9 @@ public function lt(Version $version): bool
      * @return bool True if this Version object is equal to the comparing
      *              object, otherwise false
      */
-    public function eq(Version $version): bool
+    public function eq(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) === 0;
+        return self::compare($this, $version, $comparison) === 0;
     }
 
     /**
@@ -88,9 +92,9 @@ public function eq(Version $version): bool
      * @return bool True if this Version object is not equal to the comparing
      *              object, otherwise false
      */
-    public function neq(Version $version): bool
+    public function neq(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) !== 0;
+        return self::compare($this, $version, $comparison) !== 0;
     }
 
     /**
@@ -101,9 +105,9 @@ public function neq(Version $version): bool
      * @return bool True if this Version object is greater than or equal to the
      *              comparing object, otherwise false
      */
-    public function gte(Version $version): bool
+    public function gte(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) >= 0;
+        return self::compare($this, $version, $comparison) >= 0;
     }
 
     /**
@@ -114,8 +118,8 @@ public function gte(Version $version): bool
      * @return bool True if this Version object is less than or equal to the
      *              comparing object, otherwise false
      */
-    public function lte(Version $version): bool
+    public function lte(Version $version, Compare $comparison = Compare::FULL): bool
     {
-        return self::compare($this, $version) <= 0;
+        return self::compare($this, $version, $comparison) <= 0;
     }
 }