Add PHPStan type extension for the replaceCallback callable

extension.neon

@@ -12,6 +12,10 @@ services:
         class: Composer\Pcre\PHPStan\PregMatchTypeSpecifyingExtension
         tags:
             - phpstan.typeSpecifier.staticMethodTypeSpecifyingExtension
+    -
+        class: Composer\Pcre\PHPStan\PregReplaceCallbackClosureTypeExtension
+        tags:
+            - phpstan.staticMethodParameterClosureTypeExtension
 
 rules:
     - Composer\Pcre\PHPStan\UnsafeStrictGroupsCallRule

phpstan-baseline.neon

@@ -10,6 +10,11 @@ parameters:
 			count: 1
 			path: src/Preg.php
 
+		-
+			message: "#^Creating new PHPStan\\\\Reflection\\\\Native\\\\NativeParameterReflection is not covered by backward compatibility promise\\. The class might change in a minor PHPStan version\\.$#"
+			count: 1
+			path: src/PHPStan/PregReplaceCallbackClosureTypeExtension.php
+
 		-
 			message: "#^Parameter \\#2 \\$callback of function preg_replace_callback expects callable\\(array\\<int\\|string, string\\>\\)\\: string, \\(callable\\(array\\<int\\|string, array\\{string\\|null, int\\<\\-1, max\\>\\}\\>\\)\\: string\\)\\|\\(callable\\(array\\<int\\|string, string\\|null\\>\\)\\: string\\) given\\.$#"
 			count: 2

src/PHPStan/PregReplaceCallbackClosureTypeExtension.php

@@ -0,0 +1,67 @@
+<?php declare(strict_types=1);
+
+namespace Composer\Pcre\PHPStan;
+
+use Composer\Pcre\Preg;
+use Composer\Pcre\Regex;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\Native\NativeParameterReflection;
+use PHPStan\Reflection\ParameterReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\ClosureType;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\StaticMethodParameterClosureTypeExtension;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+
+final class PregReplaceCallbackClosureTypeExtension implements StaticMethodParameterClosureTypeExtension
+{
+    /**
+     * @var RegexArrayShapeMatcher
+     */
+    private $regexShapeMatcher;
+
+    public function __construct(RegexArrayShapeMatcher $regexShapeMatcher)
+    {
+        $this->regexShapeMatcher = $regexShapeMatcher;
+    }
+
+    public function isStaticMethodSupported(MethodReflection $methodReflection, ParameterReflection $parameter): bool
+    {
+        return in_array($methodReflection->getDeclaringClass()->getName(), [Preg::class, Regex::class], true)
+            && in_array($methodReflection->getName(), ['replaceCallback'], true)
+            && $parameter->getName() === 'replacement';
+    }
+
+    public function getTypeFromStaticMethodCall(MethodReflection $methodReflection, StaticCall $methodCall, ParameterReflection $parameter, Scope $scope): ?Type
+    {
+        $args = $methodCall->getArgs();
+        $patternArg = $args[0] ?? null;
+        $flagsArg = $args[5] ?? null;
+
+        if (
+            $patternArg === null
+        ) {
+            return null;
+        }
+
+        $flagsType = null;
+        if ($flagsArg !== null) {
+            $flagsType = $scope->getType($flagsArg->value);
+        }
+
+        $matchesType = $this->regexShapeMatcher->matchExpr($patternArg->value, $flagsType, TrinaryLogic::createYes(), $scope);
+        if ($matchesType === null) {
+            return null;
+        }
+
+        return new ClosureType(
+            [
+                new NativeParameterReflection($parameter->getName(), $parameter->isOptional(), $matchesType, $parameter->passedByReference(), $parameter->isVariadic(), $parameter->getDefaultValue()),
+            ],
+            new StringType()
+        );
+    }
+}

tests/PHPStanTests/nsrt/preg-replace-callback.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace PregMatchShapes;
+
+use Composer\Pcre\Preg;
+use Composer\Pcre\Regex;
+use function PHPStan\Testing\assertType;
+
+function (string $s): void {
+    Preg::replaceCallback(
+        $s,
+        function ($matches) {
+            assertType('array<int|string, string|null>', $matches);
+            return '';
+        },
+        $s
+    );
+
+    Regex::replaceCallback(
+        $s,
+        function ($matches) {
+            assertType('array<int|string, string|null>', $matches);
+            return '';
+        },
+        $s
+    );
+};
+
+function (string $s): void {
+    Preg::replaceCallback(
+        '|<p>(\s*)\w|',
+        function ($matches) {
+            assertType('array{string, string}', $matches);
+            return '';
+        },
+        $s
+    );
+};
+
+function (string $s): void {
+    Preg::replaceCallback(
+        '/(foo)?(bar)?(baz)?/',
+        function ($matches) {
+            assertType("array{string, 'foo'|null, 'bar'|null, 'baz'|null}", $matches);
+            return '';
+        },
+        $s,
+        -1,
+        $count,
+        PREG_UNMATCHED_AS_NULL
+    );
+};
+
+function (string $s): void {
+    Preg::replaceCallback(
+        '/(foo)?(bar)?(baz)?/',
+        function ($matches) {
+            assertType("array{0: array{string, int<-1, max>}, 1?: array{''|'foo', int<-1, max>}, 2?: array{''|'bar', int<-1, max>}, 3?: array{'baz', int<-1, max>}}", $matches);
+            return '';
+        },
+        $s,
+        -1,
+        $count,
+        PREG_OFFSET_CAPTURE
+    );
+};
+
+function (string $s): void {
+    Preg::replaceCallback(
+        '/(foo)?(bar)?(baz)?/',
+        function ($matches) {
+            assertType("array{array{string|null, int<-1, max>}, array{'foo'|null, int<-1, max>}, array{'bar'|null, int<-1, max>}, array{'baz'|null, int<-1, max>}}", $matches);
+            return '';
+        },
+        $s,
+        -1,
+        $count,
+        PREG_OFFSET_CAPTURE|PREG_UNMATCHED_AS_NULL
+    );
+};