Implement array shapes for Preg::match $matches by-ref parameter

composer.json

@@ -20,8 +20,8 @@
         "php": "^7.4 || ^8.0"
     },
     "require-dev": {
-        "symfony/phpunit-bridge": "^5",
-        "phpstan/phpstan": "^1.3",
+        "phpunit/phpunit": "^9.5",
+        "phpstan/phpstan": "1.11.x-dev",
         "phpstan/phpstan-strict-rules": "^1.1"
     },
     "autoload": {

extension.neon

@@ -0,0 +1,14 @@
+# composer/pcre PHPStan extensions
+#
+# These can be reused by third party packages by including 'vendor/composer/pcre/extension.neon'
+# in your phpstan config
+
+services:
+    -
+        class: Composer\Pcre\PHPStan\PregMatchParameterOutTypeExtension
+        tags:
+            - phpstan.staticMethodParameterOutTypeExtension
+    -
+        class: Composer\Pcre\PHPStan\PregMatchTypeSpecifyingExtension
+        tags:
+            - phpstan.typeSpecifier.staticMethodTypeSpecifyingExtension

phpstan.neon.dist

@@ -6,10 +6,14 @@ parameters:
 
     treatPhpDocTypesAsCertain: false
 
-    bootstrapFiles:
-        - tests/phpstan-locate-phpunit-autoloader.php
+    ignoreErrors:
+        - '#Test::data[a-zA-Z0-9_]+\(\) return type has no value type specified in iterable type#'
+
+    excludePaths:
+        - tests/PHPStanTests/nsrt/*
 
 includes:
+    - extension.neon
     - vendor/phpstan/phpstan/conf/bleedingEdge.neon
     - vendor/phpstan/phpstan-strict-rules/rules.neon
     - phpstan-baseline.neon

src/PHPStan/PregMatchParameterOutTypeExtension.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types = 1);
+
+namespace Composer\Pcre\PHPStan;
+
+use Composer\Pcre\Preg;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParameterReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\MethodParameterOutTypeExtension;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\StaticMethodParameterOutTypeExtension;
+use PHPStan\Type\Type;
+use function in_array;
+use function strtolower;
+
+final class PregMatchParameterOutTypeExtension implements StaticMethodParameterOutTypeExtension
+{
+
+    private RegexArrayShapeMatcher $regexShapeMatcher;
+	public function __construct(
+		RegexArrayShapeMatcher $regexShapeMatcher
+	)
+	{
+        $this->regexShapeMatcher = $regexShapeMatcher;
+	}
+
+    public function isStaticMethodSupported(MethodReflection $methodReflection, ParameterReflection $parameter): bool
+    {
+        return
+            $methodReflection->getDeclaringClass()->getName() === Preg::class
+            && $methodReflection->getName() === 'match'
+            && $parameter->getName() === 'matches'
+        ;
+    }
+
+    public function getParameterOutTypeFromStaticMethodCall(MethodReflection $methodReflection, StaticCall $methodCall, ParameterReflection $parameter, Scope $scope): ?Type
+    {
+		$args = $methodCall->getArgs();
+		$patternArg = $args[0] ?? null;
+		$matchesArg = $args[2] ?? null;
+		$flagsArg = $args[3] ?? null;
+
+		if (
+			$patternArg === null || $matchesArg === null
+		) {
+			return null;
+		}
+
+		$patternType = $scope->getType($patternArg->value);
+		$flagsType = null;
+		if ($flagsArg !== null) {
+			$flagsType = $scope->getType($flagsArg->value);
+		}
+
+		return $this->regexShapeMatcher->matchType($patternType, $flagsType, TrinaryLogic::createMaybe());
+	}
+
+}

src/PHPStan/PregMatchTypeSpecifyingExtension.php

@@ -0,0 +1,93 @@
+<?php declare(strict_types = 1);
+
+namespace Composer\Pcre\PHPStan;
+
+use Composer\Pcre\Preg;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Analyser\SpecifiedTypes;
+use PHPStan\Analyser\TypeSpecifier;
+use PHPStan\Analyser\TypeSpecifierAwareExtension;
+use PHPStan\Analyser\TypeSpecifierContext;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\FunctionTypeSpecifyingExtension;
+use PHPStan\Type\MethodTypeSpecifyingExtension;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\StaticMethodTypeSpecifyingExtension;
+use function in_array;
+use function strtolower;
+
+final class PregMatchTypeSpecifyingExtension implements StaticMethodTypeSpecifyingExtension, TypeSpecifierAwareExtension
+{
+
+	private TypeSpecifier $typeSpecifier;
+
+    private RegexArrayShapeMatcher $regexShapeMatcher;
+
+    public function __construct(
+        RegexArrayShapeMatcher $regexShapeMatcher
+    )
+    {
+        $this->regexShapeMatcher = $regexShapeMatcher;
+    }
+
+
+	public function setTypeSpecifier(TypeSpecifier $typeSpecifier): void
+	{
+		$this->typeSpecifier = $typeSpecifier;
+	}
+
+    public function getClass(): string {
+        return Preg::class;
+    }
+
+    public function isStaticMethodSupported(MethodReflection $methodReflection, StaticCall $node, TypeSpecifierContext $context) : bool
+    {
+        return $methodReflection->getName() === 'match' && !$context->null();
+    }
+
+    public function specifyTypes(MethodReflection $methodReflection, StaticCall $node, Scope $scope, TypeSpecifierContext $context) : SpecifiedTypes
+    {
+		$args = $node->getArgs();
+		$patternArg = $args[0] ?? null;
+		$matchesArg = $args[2] ?? null;
+		$flagsArg = $args[3] ?? null;
+
+		if (
+			$patternArg === null || $matchesArg === null
+		) {
+			return new SpecifiedTypes();
+		}
+
+		$patternType = $scope->getType($patternArg->value);
+		$flagsType = null;
+		if ($flagsArg !== null) {
+			$flagsType = $scope->getType($flagsArg->value);
+		}
+
+		$matchedType = $this->regexShapeMatcher->matchType($patternType, $flagsType, TrinaryLogic::createFromBoolean($context->true()));
+		if ($matchedType === null) {
+			return new SpecifiedTypes();
+		}
+
+		$overwrite = false;
+		if ($context->false()) {
+			$overwrite = true;
+			$context = $context->negate();
+		}
+
+		return $this->typeSpecifier->create(
+			$matchesArg->value,
+			$matchedType,
+			$context,
+			$overwrite,
+			$scope,
+			$node,
+		);
+	}
+
+}

tests/PHPStanTests/TypeInferenceTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of composer/pcre.
+ *
+ * (c) Composer <https://github.com/composer>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Composer\Pcre\PHPStanTests;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+
+class TypeInferenceTest extends TypeInferenceTestCase
+{
+    public function dataFileAsserts(): iterable
+    {
+        yield from $this->gatherAssertTypesFromDirectory(__DIR__ . '/nsrt');
+
+    }
+
+    /**
+     * @dataProvider dataFileAsserts
+     * @param mixed ...$args
+     */
+    public function testFileAsserts(
+        string $assertType,
+        string $file,
+               ...$args
+	): void
+	{
+        $this->assertFileAsserts($assertType, $file, ...$args);
+    }
+
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [
+            __DIR__ . '/../../extension.neon',
+        ];
+    }
+}

tests/PHPStanTests/nsrt/preg-match.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace PregMatchShapes;
+
+use Composer\Pcre\Preg;
+use function PHPStan\Testing\assertType;
+
+function doMatch(string $s): void
+{
+    if (Preg::match('/Price: /i', $s, $matches)) {
+        assertType('array{string}', $matches);
+    }
+    assertType('array{}|array{string}', $matches);
+
+    if (Preg::match('/Price: (£|€)\d+/', $s, $matches)) {
+        assertType('array{string, string}', $matches);
+    } else {
+        assertType('array{}', $matches);
+    }
+    assertType('array{}|array{string, string}', $matches);
+}