Add regex wrapper

Author: iquito

README.md

@@ -10,6 +10,7 @@ Handles common string operations in PHP applications:
 - [Generate a random string](#generate-a-random-string) with a set of characters
 - [Condense a number into a string](#condense-a-string-into-a-number), and convert/expand a string into a number
 - [Process an URL](#url) and modify it in a safe way (convert to relative URL, change parts of it, etc.)
+- [Regex wrapper](#regex-wrapper) to better handle type hints and errors with the most common regex functions
 
 Filter a string
 ---------------
@@ -318,4 +319,9 @@ The URL class accepts an URL in the constructor and then lets you get or change
 - Change scheme, host, path and query string
 - Replace query string variables, or add/remove them
 
-This can be used to easily build or change your URLs, or to sanitize certain parts of a given URL, for example when redirecting: use the relative URL instead of the absolute URL to avoid malicious redirecting to somewhere outside of your control.
+This can be used to easily build or change your URLs, or to sanitize certain parts of a given URL, for example when redirecting: use the relative URL instead of the absolute URL to avoid malicious redirecting to somewhere outside of your control.
+
+Regex wrapper
+-------------
+
+Using the built-in `preg_match`, `preg_match_all`, `preg_replace` and `preg_replace_callback` functions often makes code less readable and harder to understand for static analyzers. `Squirrel\Strings\Regex` wraps the basic functionality of these preg functions and throws a `Squirrel\Strings\Exception\RegexException` if anything goes wrong.

src/Common/RegexExceptionTrait.php

@@ -16,9 +16,6 @@ trait RegexExceptionTrait
 {
     private function generateRegexException(): \Throwable
     {
-        /**
-         * @var array $constants
-         */
         $constants = \get_defined_constants(true)['pcre'];
 
         // Find the regex error code

src/Regex.php

@@ -0,0 +1,149 @@
+<?php
+
+namespace Squirrel\Strings;
+
+use Squirrel\Debug\Debug;
+use Squirrel\Strings\Exception\RegexException;
+
+/**
+ * Wrapper around common regex functions for better type hints and error handling
+ */
+final class Regex
+{
+    /**
+     * @pure
+     *
+     * @throws RegexException
+     */
+    public static function isMatch(
+        string $pattern,
+        string $subject,
+        int $offset = 0,
+    ): bool {
+        $result = @\preg_match($pattern, $subject, offset: $offset);
+
+        if (!\is_int($result)) {
+            throw self::generateRegexException();
+        }
+
+        return \boolval($result);
+    }
+
+    /**
+     * @pure
+     *
+     * @throws RegexException
+     */
+    public static function getMatches(
+        string $pattern,
+        string $subject,
+        int $flags = 0,
+        int $offset = 0,
+    ): ?array {
+        $result = @\preg_match_all($pattern, $subject, $matches, $flags, $offset);
+
+        if (!\is_int($result)) {
+            throw self::generateRegexException();
+        }
+
+        if ($result === 0) {
+            return null;
+        }
+
+        return $matches;
+    }
+
+    /**
+     * @pure
+     *
+     * @throws RegexException
+     */
+    public static function replace(
+        string|array $pattern,
+        string|array $replacement,
+        string $subject,
+        int $limit = -1,
+    ): string {
+        $result = @\preg_replace($pattern, $replacement, $subject, $limit);
+
+        if (!\is_string($result)) {
+            throw self::generateRegexException();
+        }
+
+        return $result;
+    }
+
+    /**
+     * @pure
+     *
+     * @throws RegexException
+     */
+    public static function replaceArray(
+        string|array $pattern,
+        string|array $replacement,
+        array $subject,
+        int $limit = -1,
+    ): array {
+        $result = [];
+
+        foreach ($subject as $key => $singleSubject) {
+            $result[$key] = self::replace($pattern, $replacement, $singleSubject, $limit);
+        }
+
+        return $result;
+    }
+
+    /**
+     * @throws RegexException
+     */
+    public static function replaceWithCallback(
+        string|array $pattern,
+        callable $callback,
+        string $subject,
+        int $limit = -1,
+        int $flags = 0,
+    ): string {
+        $result = @\preg_replace_callback($pattern, $callback, $subject, $limit, flags: $flags);
+
+        if (!\is_string($result)) {
+            throw self::generateRegexException();
+        }
+
+        return $result;
+    }
+
+    /**
+     * @throws RegexException
+     */
+    public static function replaceArrayWithCallback(
+        string|array $pattern,
+        callable $callback,
+        array $subject,
+        int $limit = -1,
+        int $flags = 0,
+    ): array {
+        $result = [];
+
+        foreach ($subject as $key => $singleSubject) {
+            $result[$key] = self::replaceWithCallback($pattern, $callback, $singleSubject, $limit, flags: $flags);
+        }
+
+        return $result;
+    }
+
+    private static function generateRegexException(): \Throwable
+    {
+        $constants = \get_defined_constants(true)['pcre'];
+
+        // Find the regex error code
+        foreach ($constants as $name => $value) {
+            if ($value === \preg_last_error()) {
+                $error = $name;
+            }
+        }
+
+        return Debug::createException(RegexException::class, [
+            self::class,
+        ], 'Regex error in ' . __CLASS__ . ': ' . ( $error ?? 'Unrecognized error code' ));
+    }
+}