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

composer.json

@@ -20,10 +20,13 @@
  "php": "^7.4 || ^8.0"
  },
  "require-dev": {
- "symfony/phpunit-bridge": "^5",
- "phpstan/phpstan": "^1.3",
+ "phpunit/phpunit": "^9.5",
+ "phpstan/phpstan": "^1.11.6",
  "phpstan/phpstan-strict-rules": "^1.1"
  },
+ "conflict": {
+ "phpstan/phpstan": "<1.11.6"
+ },
  "autoload": {
  "psr-4": {
  "Composer\\Pcre\\": "src"

extension.neon

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

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/PregMatchFlags.php

@@ -0,0 +1,35 @@
+<?php declare(strict_types=1);
+
+namespace Composer\Pcre\PHPStan;
+
+use PHPStan\Analyser\Scope;
+use PHPStan\Type\Constant\ConstantIntegerType;
+use PHPStan\Type\TypeCombinator;
+use PHPStan\Type\Type;
+
+final class PregMatchFlags
+{
+ static public function getType(?Arg $flagsArg, Scope $scope): ?Type
+ {
+ if ($flagsArg === null) {
+ return new ConstantIntegerType(PREG_UNMATCHED_AS_NULL);
+ }
+
+ $flagsType = $scope->getType($flagsArg->value);
+
+ $constantScalars = $flagsType->getConstantScalarValues();
+ if ($constantScalars === []) {
+ return null;
+ }
+
+ $internalFlagsTypes = [];
+ foreach ($flagsType->getConstantScalarValues() as $constantScalarValue) {
+ if (!is_int($constantScalarValue)) {
+ return null;
+ }
+
+ $internalFlagsTypes[] = $constantScalarValue | PREG_UNMATCHED_AS_NULL;
+ }
+ return TypeCombinator::union(...$internalFlagsTypes);
+ }
+}

src/PHPStan/PregMatchParameterOutTypeExtension.php

@@ -0,0 +1,57 @@
+<?php declare(strict_types=1);
+
+namespace Composer\Pcre\PHPStan;
+
+use Composer\Pcre\Preg;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParameterReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\StaticMethodParameterOutTypeExtension;
+use PHPStan\Type\Type;
+
+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;
+ }
+
+ $flagsType = PregMatchFlags::getType($flagsArg, $scope);
+ if ($flagsType === null) {
+ return null;
+ }
+ $patternType = $scope->getType($patternArg->value);
+
+ return $this->regexShapeMatcher->matchType($patternType, $flagsType, TrinaryLogic::createMaybe());
+ }
+
+}

src/PHPStan/PregMatchTypeSpecifyingExtension.php

@@ -0,0 +1,87 @@
+<?php declare(strict_types=1);
+
+namespace Composer\Pcre\PHPStan;
+
+use Composer\Pcre\Preg;
+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\MethodReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\Php\RegexArrayShapeMatcher;
+use PHPStan\Type\StaticMethodTypeSpecifyingExtension;
+
+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();
+ }
+
+ $flagsType = PregMatchFlags::getType($flagsArg, $scope);
+ if ($flagsType === null) {
+ return new SpecifiedTypes();
+ }
+ $patternType = $scope->getType($patternArg->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,44 @@
+<?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 [
+ 'phar://' . __DIR__ . '/../../vendor/phpstan/phpstan/phpstan.phar/conf/bleedingEdge.neon',
+ __DIR__ . '/../../extension.neon',
+ ];
+ }
+}

tests/PHPStanTests/nsrt/preg-match.php

@@ -0,0 +1,50 @@
+<?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);
+ } else {
+ assertType('array{}', $matches);
+ }
+ assertType('array{}|array{string}', $matches);
+
+ if (Preg::match('/Price: (£|€)\d+/', $s, $matches)) {
+ assertType('array{string, string|null}', $matches);
+ } else {
+ assertType('array{}', $matches);
+ }
+ assertType('array{}|array{string, string|null}', $matches);
+
+ if (Preg::match('/Price: (£|€)?\d+/', $s, $matches)) {
+ assertType('array{0: string, 1?: string|null}', $matches);
+ } else {
+ assertType('array{}', $matches);
+ }
+ assertType('array{}|array{0: string, 1?: string|null}', $matches);
+}
+
+function identicalMatch(string $s): void
+{
+ if (Preg::match('/Price: /i', $s, $matches) === 1) {
+ assertType('array{string}', $matches);
+ } else {
+ assertType('array{}', $matches);
+ }
+ assertType('array{}|array{string}', $matches);
+}
+
+function equalMatch(string $s): void
+{
+ if (Preg::match('/Price: /i', $s, $matches) == 1) {
+ assertType('array{string}', $matches);
+ } else {
+ assertType('array{}', $matches);
+ }
+ assertType('array{}|array{string}', $matches);
+}