feat!: improve id matching methods on the id contract

Author: lindyhopchris

CHANGELOG.md

@@ -9,6 +9,12 @@ All notable changes to this project will be documented in this file. This projec
 
 - The `once` method has been added to the server repository interface. This previously existed on the concrete class,
   but has now been added to the interface.
+- The schema `ID` contract now has a `matchAll()` method for matching multiple ids at once.
+
+### Changed
+
+- **BREAKING** The `match()` method on the schema `ID` contract now accepts an optional delimiter as its second
+  argument. When receiving a delimiter, the input value can have one-to-many ids separated by the provided delimiter.
 
 ## Unreleased
 

src/Contracts/Schema/ID.php

@@ -31,10 +31,22 @@ public function pattern(): string;
     /**
      * Does the value match the pattern?
      *
+     * If a delimiter is provided, the value can hold one-to-many ids separated
+     * by the provided delimiter.
+     *
      * @param string $value
+     * @param string $delimiter
+     * @return bool
+     */
+    public function match(string $value, string $delimiter = ''): bool;
+
+    /**
+     * Do all the values match the pattern?
+     *
+     * @param array<string> $values
      * @return bool
      */
-    public function match(string $value): bool;
+    public function matchAll(array $values): bool;
 
     /**
      * Does the resource accept client generated ids?

src/Core/Schema/Concerns/MatchesIds.php

@@ -79,13 +79,42 @@ public function matchCase(): static
     }
 
     /**
-     * Does the value match the ID's pattern?
+     * Does the value match the pattern?
      *
-     * @param string $resourceId
+     * If a delimiter is provided, the value can hold one-to-many ids separated
+     * by the provided delimiter.
+     *
+     * @param string $value
+     * @param string $delimiter
+     * @return bool
+     */
+    public function match(string $value, string $delimiter = ''): bool
+    {
+        if (strlen($delimiter) > 0) {
+            $delimiter = preg_quote($delimiter);
+            return 1 === preg_match(
+                "/^{$this->pattern}({$delimiter}{$this->pattern})*$/{$this->flags}",
+                $value,
+            );
+        }
+
+        return 1 === preg_match("/^{$this->pattern}$/{$this->flags}", $value);
+    }
+
+    /**
+     * Do all the values match the pattern?
+     *
+     * @param array<string> $values
      * @return bool
      */
-    public function match(string $resourceId): bool
+    public function matchAll(array $values): bool
     {
-        return 1 === preg_match("/^{$this->pattern}$/{$this->flags}", $resourceId);
+        foreach ($values as $value) {
+            if ($this->match($value) === false) {
+                return false;
+            }
+        }
+
+        return true;
     }
 }

tests/Unit/Schema/Concerns/MatchesIdsTest.php

@@ -27,7 +27,13 @@ public function testItIsNumeric(): void
 
         $this->assertSame('[0-9]+', $id->pattern());
         $this->assertTrue($id->match('1234'));
+        $this->assertTrue($id->match('1234,5678,90', ','));
+        $this->assertTrue($id->match('1234-5678-90', '-'));
+        $this->assertTrue($id->match('1234', ','));
+        $this->assertTrue($id->matchAll(['1234', '5678', '90']));
         $this->assertFalse($id->match('123A45'));
+        $this->assertFalse($id->match('1234,567E,1234', ','));
+        $this->assertFalse($id->matchAll(['1234', '5678', '90E']));
     }
 
     /**
@@ -39,10 +45,21 @@ public function testItIsUuid(): void
             use MatchesIds;
         };
 
+        $uuids = [
+            '1e1cc75c-dc37-488d-b862-828529088261',
+            'fca1509e-9178-45fd-8a2b-ae819d34f7e6',
+            '2935a487-85e1-4f3c-b585-cd64e9a776f3',
+        ];
+
         $this->assertSame($id, $id->uuid());
         $this->assertSame('[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}', $id->pattern());
-        $this->assertTrue($id->match('fca1509e-9178-45fd-8a2b-ae819d34f7e6'));
+        $this->assertTrue($id->match($uuids[0]));
+        $this->assertTrue($id->match(implode(',', $uuids), ','));
+        $this->assertTrue($id->match($uuids[0], ','));
+        $this->assertTrue($id->matchAll($uuids));
         $this->assertFalse($id->match('fca1509e917845fd8a2bae819d34f7e6'));
+        $this->assertFalse($id->match(implode(',', $invalid = [...$uuids, 'fca1509e917845fd8a2bae819d34f7e6']), ','));
+        $this->assertFalse($id->matchAll($invalid));
     }
 
     /**
@@ -54,10 +71,20 @@ public function testItIsUlid(): void
             use MatchesIds;
         };
 
+        $ulids = [
+            '01HT4PA8AZC8Q30ZGC5PEWZP0E',
+            '01HT4QSVZXQX89AZNSXGYYB3PB',
+            '01HT4QT51KE7NJ12SDS48N3CWB',
+        ];
+
         $this->assertSame($id, $id->ulid());
         $this->assertSame('[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}', $id->pattern());
-        $this->assertTrue($id->match('01HT4PA8AZC8Q30ZGC5PEWZP0E'));
+        $this->assertTrue($id->match($ulids[0]));
+        $this->assertTrue($id->match(implode(',', $ulids), ','));
+        $this->assertTrue($id->matchAll($ulids));
         $this->assertFalse($id->match('01HT4PA8AZC8Q30ZGC5PEWZP0'));
+        $this->assertFalse($id->match(implode(',', $invalid = [...$ulids, '01HT4PA8AZC8Q30ZGC5PEWZP0']), ','));
+        $this->assertFalse($id->matchAll($invalid));
     }
 
     /**