Understand the exact array shape coming from Nette\Utils\Strings::matchAll() based on pattern

Author: ondrejmirtes

composer.json

@@ -7,7 +7,7 @@
 	],
 	"require": {
 		"php": "^7.2 || ^8.0",
-		"phpstan/phpstan": "^1.11.8"
+		"phpstan/phpstan": "^1.11.9"
 	},
 	"conflict": {
 		"nette/application": "<2.3.0",

extension.neon

@@ -55,6 +55,8 @@ parameters:
 conditionalTags:
 	PHPStan\Type\Nette\StringsMatchDynamicReturnTypeExtension:
 		phpstan.broker.dynamicStaticMethodReturnTypeExtension: %featureToggles.narrowPregMatches%
+	PHPStan\Type\Nette\StringsMatchAllDynamicReturnTypeExtension:
+		phpstan.broker.dynamicStaticMethodReturnTypeExtension: %featureToggles.narrowPregMatches%
 
 services:
 	-
@@ -119,5 +121,8 @@ services:
 		tags:
 			- phpstan.properties.readWriteExtension
 
+	-
+		class: PHPStan\Type\Nette\StringsMatchAllDynamicReturnTypeExtension
+
 	-
 		class: PHPStan\Type\Nette\StringsMatchDynamicReturnTypeExtension

src/Type/Nette/StringsMatchAllDynamicReturnTypeExtension.php

@@ -0,0 +1,59 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Nette;
+
+use Nette\Utils\Strings;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+
+class StringsMatchAllDynamicReturnTypeExtension implements DynamicStaticMethodReturnTypeExtension
+{
+
+	/** @var RegexArrayShapeMatcher */
+	private $regexArrayShapeMatcher;
+
+	public function __construct(RegexArrayShapeMatcher $regexArrayShapeMatcher)
+	{
+		$this->regexArrayShapeMatcher = $regexArrayShapeMatcher;
+	}
+
+	public function getClass(): string
+	{
+		return Strings::class;
+	}
+
+	public function isStaticMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'matchAll';
+	}
+
+	public function getTypeFromStaticMethodCall(MethodReflection $methodReflection, StaticCall $methodCall, Scope $scope): ?Type
+	{
+		$args = $methodCall->getArgs();
+		$patternArg = $args[1] ?? null;
+		if ($patternArg === null) {
+			return null;
+		}
+
+		$flagsArg = $args[2] ?? null;
+		$flagsType = null;
+		if ($flagsArg !== null) {
+			$flagsType = $scope->getType($flagsArg->value);
+		}
+
+		$arrayShape = $this->regexArrayShapeMatcher->matchAllExpr($patternArg->value, $flagsType, TrinaryLogic::createYes(), $scope);
+		if ($arrayShape === null) {
+			return null;
+		}
+
+		return TypeCombinator::union($arrayShape, new NullType());
+	}
+
+}

tests/Type/Nette/data/strings-match.php

@@ -5,6 +5,7 @@
 use Nette\Utils\Strings;
 use function PHPStan\Testing\assertType;
 use const PREG_OFFSET_CAPTURE;
+use const PREG_SET_ORDER;
 
 function (string $s): void {
 	$result = Strings::match($s, '/%env\((.*)\:.*\)%/U');
@@ -22,3 +23,13 @@ function (string $s): void {
 	$result = Strings::match($s, '/(foo)(bar)'. preg_quote($s) .'(baz)/');
 	assertType('array{string, non-empty-string, non-empty-string, non-empty-string}|null', $result);
 };
+
+function (string $s): void {
+	$result = Strings::matchAll($s, '/ab(?P<num>\d+)(?P<suffix>ab)?/', PREG_SET_ORDER);
+	assertType("list<array{0: string, num: numeric-string, 1: numeric-string, suffix?: non-empty-string, 2?: non-empty-string}>|null", $result);
+};
+
+function (string $s): void {
+	$result = Strings::matchAll($s, '/ab(?P<num>\d+)(?P<suffix>ab)?/', PREG_PATTERN_ORDER);
+	assertType("array{0: list<string>, num: list<numeric-string>, 1: list<numeric-string>, suffix: list<string>, 2: list<string>}|null", $result);
+};