Also add replaceCallbackStrictGroups as 3.x can rely on PREG_UNMATCHED_AS_NULL for preg_replace_callback (#15)

Author: Seldaek

src/Preg.php

@@ -192,6 +192,24 @@ public static function replaceCallback($pattern, callable $replacement, $subject
         return $result;
     }
 
+    /**
+     * Variant of `replaceCallback()` which outputs non-null matches (or throws)
+     *
+     * @param string $pattern
+     * @param callable(array<int|string, string>): string $replacement
+     * @param string $subject
+     * @param int $count Set by method
+     * @param int-mask<PREG_UNMATCHED_AS_NULL|PREG_OFFSET_CAPTURE> $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     *
+     * @param-out int<0, max> $count
+     */
+    public static function replaceCallbackStrictGroups(string $pattern, callable $replacement, $subject, int $limit = -1, int &$count = null, int $flags = 0): string
+    {
+        return self::replaceCallback($pattern, function (array $matches) use ($pattern, $replacement) {
+            return $replacement(self::enforceNonNullMatches($pattern, $matches, 'replaceCallback'));
+        }, $subject, $limit, $count, $flags);
+    }
+
     /**
      * @param array<string, callable(array<int|string, string|null>): string> $pattern
      * @param string $subject

src/Regex.php

@@ -131,6 +131,21 @@ public static function replaceCallback($pattern, callable $replacement, $subject
         return new ReplaceResult($count, $result);
     }
 
+    /**
+     * Variant of `replaceCallback()` which outputs non-null matches (or throws)
+     *
+     * @param string $pattern
+     * @param callable(array<int|string, string>): string $replacement
+     * @param string          $subject
+     * @param int-mask<PREG_UNMATCHED_AS_NULL|PREG_OFFSET_CAPTURE> $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     */
+    public static function replaceCallbackStrictGroups($pattern, callable $replacement, $subject, int $limit = -1, int $flags = 0): ReplaceResult
+    {
+        $result = Preg::replaceCallbackStrictGroups($pattern, $replacement, $subject, $limit, $count, $flags);
+
+        return new ReplaceResult($count, $result);
+    }
+
     /**
      * @param array<string, callable(array<int|string, string|null>): string> $pattern
      * @param string $subject

tests/PregTests/ReplaceCallbackTest.php

@@ -13,6 +13,7 @@
 
 use Composer\Pcre\BaseTestCase;
 use Composer\Pcre\Preg;
+use Composer\Pcre\UnexpectedNullMatchException;
 
 class ReplaceCallbackTest extends BaseTestCase
 {
@@ -60,6 +61,26 @@ public function testFailure(): void
         self::assertSame('def', $result);
     }
 
+    public function testSuccessStrictGroups(): void
+    {
+        $result = Preg::replaceCallbackStrictGroups('{(?P<m>\d)(?<matched>a)?}', function ($match) {
+            return strtoupper($match['matched']);
+        }, '3a', -1, $count);
+
+        self::assertSame(1, $count);
+        self::assertSame('A', $result);
+    }
+
+    public function testFailStrictGroups(): void
+    {
+        self::expectException(UnexpectedNullMatchException::class);
+        self::expectExceptionMessage('Pattern "{(?P<m>\d)(?<unmatched>a)?}" had an unexpected unmatched group "unmatched", make sure the pattern always matches or use replaceCallback() instead.');
+
+        $result = Preg::replaceCallbackStrictGroups('{(?P<m>\d)(?<unmatched>a)?}', function ($match) {
+            return strtoupper($match['unmatched']);
+        }, '123', -1, $count);
+    }
+
     public function testBadPatternThrowsIfWarningsAreNotThrowing(): void
     {
         $this->expectPcreException($pattern = '{(?P<m>d)');