Switch to use PREG_UNMATCHED_AS_NULL always, drop PHP <7.4, fixes #8 (#10)

Author: Seldaek

.github/workflows/continuous-integration.yml

@@ -17,8 +17,6 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.2"
-          - "7.3"
           - "7.4"
           - "8.0"
           - "8.1"

.github/workflows/phpstan.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.2"
+          - "7.4"
           - "8.1"
 
     steps:

README.md

@@ -6,7 +6,9 @@ PCRE wrapping library that offers type-safe `preg_*` replacements.
 This library gives you a way to ensure `preg_*` functions do not fail silently, returning
 unexpected `null`s that may not be handled.
 
-As of 2.0 this library also enforces [`PREG_UNMATCHED_AS_NULL`](#preg_unmatched_as_null) usage for all matching functions, [read more below](#preg_unmatched_as_null) to understand the implications.
+As of 3.0 this library enforces [`PREG_UNMATCHED_AS_NULL`](#preg_unmatched_as_null) usage
+for all matching and replaceCallback functions, [read more below](#preg_unmatched_as_null)
+to understand the implications.
 
 It thus makes it easier to work with static analysis tools like PHPStan or Psalm as it
 simplifies and reduces the possible return values from all the `preg_*` functions which
@@ -32,7 +34,9 @@ $ composer require composer/pcre
 Requirements
 ------------
 
-* PHP 5.3.2 is required but using the latest version of PHP is highly recommended.
+* PHP 7.4.0 is required for 3.x versions
+* PHP 7.2.0 is required for 2.x versions
+* PHP 5.3.2 is required for 1.x versions
 
 
 Basic usage
@@ -125,17 +129,13 @@ Due to type safety requirements a few restrictions are in place.
 - `replace`, `replaceCallback` and `replaceCallbackArray` do not support an array `$subject`,
   only simple strings.
 - As of 2.0, the library always uses `PREG_UNMATCHED_AS_NULL` for matching, which offers [much
-  saner/more predictable results](#preg_unmatched_as_null). 3.x will also use the flag for
-  `replaceCallback` and `replaceCallbackArray`. This is currently not doable due to the PHP
-  version requirement and to keep things working the same across all PHP versions. If you use
-  the library on a PHP 7.4+ project however we highly recommend already passing
-  `PREG_UNMATCHED_AS_NULL` to `replaceCallback` and `replaceCallbackArray`.
+  saner/more predictable results](#preg_unmatched_as_null). As of 3.0 the flag is also set for
+  `replaceCallback` and `replaceCallbackArray`.
 
 #### PREG_UNMATCHED_AS_NULL
 
 As of 2.0, this library always uses PREG_UNMATCHED_AS_NULL for all `match*` and `isMatch*`
-functions (unfortunately `preg_replace_callback[_array]` only support this from PHP 7.4
-onwards so we cannot do the same there yet).
+functions. As of 3.0 it is also done for `replaceCallback` and `replaceCallbackArray`.
 
 This means your matches will always contain all matching groups, either as null if unmatched
 or as string if it matched.

composer.json

@@ -17,7 +17,7 @@
         }
     ],
     "require": {
-        "php": "^7.2 || ^8.0"
+        "php": "^7.4 || ^8.0"
     },
     "require-dev": {
         "symfony/phpunit-bridge": "^5",
@@ -36,11 +36,11 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-main": "2.x-dev"
+            "dev-main": "3.x-dev"
         }
     },
     "scripts": {
-        "test": "SYMFONY_PHPUNIT_REMOVE_RETURN_TYPEHINT=1 vendor/bin/simple-phpunit",
+        "test": "vendor/bin/simple-phpunit",
         "phpstan": "phpstan analyse"
     }
 }

phpstan-baseline.neon

@@ -15,13 +15,3 @@ parameters:
 			count: 2
 			path: src/Preg.php
 
-		-
-			message: "#^Function preg_replace_callback invoked with 6 parameters, 3\\-5 required\\.$#"
-			count: 1
-			path: src/Preg.php
-
-		-
-			message: "#^Function preg_replace_callback_array invoked with 5 parameters, 2\\-4 required\\.$#"
-			count: 1
-			path: src/Preg.php
-

src/Preg.php

@@ -130,7 +130,7 @@ public static function replace($pattern, $replacement, $subject, int $limit = -1
      * @param string|string[] $pattern
      * @param string $subject
      * @param int             $count Set by method
-     * @param int             $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     * @param int             $flags PREG_OFFSET_CAPTURE is supported, PREG_UNMATCHED_AS_NULL is always set
      */
     public static function replaceCallback($pattern, callable $replacement, $subject, int $limit = -1, int &$count = null, int $flags = 0): string
     {
@@ -142,11 +142,7 @@ public static function replaceCallback($pattern, callable $replacement, $subject
             throw new \TypeError(sprintf(static::INVALID_TYPE_MSG, gettype($subject)));
         }
 
-        if (PHP_VERSION_ID >= 70400) {
-            $result = preg_replace_callback($pattern, $replacement, $subject, $limit, $count, $flags);
-        } else {
-            $result = preg_replace_callback($pattern, $replacement, $subject, $limit, $count);
-        }
+        $result = preg_replace_callback($pattern, $replacement, $subject, $limit, $count, $flags | PREG_UNMATCHED_AS_NULL);
         if ($result === null) {
             throw PcreException::fromFunction('preg_replace_callback', $pattern);
         }
@@ -158,7 +154,7 @@ public static function replaceCallback($pattern, callable $replacement, $subject
      * @param array<string, callable> $pattern
      * @param string $subject
      * @param int    $count Set by method
-     * @param int    $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     * @param int    $flags PREG_OFFSET_CAPTURE is supported, PREG_UNMATCHED_AS_NULL is always set
      */
     public static function replaceCallbackArray(array $pattern, $subject, int $limit = -1, int &$count = null, int $flags = 0): string
     {
@@ -170,11 +166,7 @@ public static function replaceCallbackArray(array $pattern, $subject, int $limit
             throw new \TypeError(sprintf(static::INVALID_TYPE_MSG, gettype($subject)));
         }
 
-        if (PHP_VERSION_ID >= 70400) {
-            $result = preg_replace_callback_array($pattern, $subject, $limit, $count, $flags);
-        } else {
-            $result = preg_replace_callback_array($pattern, $subject, $limit, $count);
-        }
+        $result = preg_replace_callback_array($pattern, $subject, $limit, $count, $flags | PREG_UNMATCHED_AS_NULL);
         if ($result === null) {
             $pattern = array_keys($pattern);
             throw PcreException::fromFunction('preg_replace_callback_array', $pattern);

src/Regex.php

@@ -95,7 +95,7 @@ public static function replace($pattern, $replacement, $subject, int $limit = -1
     /**
      * @param string|string[] $pattern
      * @param string          $subject
-     * @param int             $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     * @param int             $flags PREG_OFFSET_CAPTURE is supported, PREG_UNMATCHED_AS_NULL is always set
      */
     public static function replaceCallback($pattern, callable $replacement, $subject, int $limit = -1, int $flags = 0): ReplaceResult
     {
@@ -107,7 +107,7 @@ public static function replaceCallback($pattern, callable $replacement, $subject
     /**
      * @param array<string, callable> $pattern
      * @param string $subject
-     * @param int    $flags PREG_OFFSET_CAPTURE or PREG_UNMATCHED_AS_NULL, only available on PHP 7.4+
+     * @param int    $flags PREG_OFFSET_CAPTURE is supported, PREG_UNMATCHED_AS_NULL is always set
      */
     public static function replaceCallbackArray(array $pattern, $subject, int $limit = -1, int $flags = 0): ReplaceResult
     {