Keep optional groups optional within a matched regex alternation branch

When building the tagged union for a single top-level alternation, the
groups of the matched branch were forced non-optional, which also dropped
their own optional quantifiers, e.g. `(?:-(?P<bar>\d+))?`. Such a group
is now only forced out of the alternation's optionality.

With PREG_UNMATCHED_AS_NULL on PHP 7.2 and 7.3, an unmatched group
followed by a matched one is reported as null, not as an empty string.
Only the trailing unmatched groups are omitted there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KjXHtRyzsYF9xktijyaRBr

Author: ondrejmirtes

src/Type/Php/RegexArrayShapeMatcher.php

@@ -197,12 +197,12 @@ private function matchRegex(string $regex, ?int $flags, TrinaryLogic $wasMatched
 				foreach ($comboList as $group) {
 					if (in_array($group->getId(), $groupCombo, true)) {
 						$isOptionalAlternation = $group->inOptionalAlternation();
-						$comboList = $comboList->forceGroupNonOptional($group);
+						$comboList = $comboList->forceGroupAlternationBranchMatched($group);
 						$beforeCurrentCombo = false;
 					} elseif ($beforeCurrentCombo && !$group->resetsGroupCounter()) {
 						$comboList = $comboList->forceGroupTypeAndNonOptional(
 							$group,
-							$this->containsUnmatchedAsNull($flags, $matchesAll) ? new NullType() : new ConstantStringType(''),
+							$this->getUnmatchedGroupType($flags),
 						);
 					} elseif (
 						$group->getAlternationId() === $onlyTopLevelAlternation->getId()
@@ -438,7 +438,7 @@ private function createGroupValueType(RegexCapturingGroup $captureGroup, Trinary
 
 		if (!$isLastGroup && !$this->containsUnmatchedAsNull($flags, $matchesAll) && $captureGroup->isOptional()) {
 			$groupValueType = $this->getValueType(
-				TypeCombinator::union($captureGroup->getType(), new ConstantStringType('')),
+				TypeCombinator::union($captureGroup->getType(), $this->getUnmatchedGroupType($flags)),
 				$flags,
 				$matchesAll,
 			);
@@ -482,6 +482,21 @@ private function containsUnmatchedAsNull(int $flags, bool $matchesAll): bool
 		return ($flags & PREG_UNMATCHED_AS_NULL) !== 0 && (($flags & self::PREG_UNMATCHED_AS_NULL_ON_72_73) !== 0 || $this->phpVersion->supportsPregUnmatchedAsNull());
 	}
 
+	/**
+	 * Type of an unmatched group followed by a matched one.
+	 *
+	 * PHP 7.2 and 7.3 already report it as null with PREG_UNMATCHED_AS_NULL,
+	 * only the trailing unmatched groups are omitted there.
+	 */
+	private function getUnmatchedGroupType(int $flags): Type
+	{
+		if (($flags & PREG_UNMATCHED_AS_NULL) !== 0) {
+			return new NullType();
+		}
+
+		return new ConstantStringType('');
+	}
+
 	private function getKeyType(int|string $key): Type
 	{
 		if (is_string($key)) {

src/Type/Regex/RegexCapturingGroup.php

@@ -16,6 +16,7 @@ public function __construct(
 		private readonly Type $type,
 		private readonly bool $forceNonOptional = false,
 		private readonly ?Type $forceType = null,
+		private readonly bool $forceAlternationBranchMatched = false,
 	)
 	{
 	}
@@ -36,6 +37,26 @@ public function forceNonOptional(): self
 			$this->type,
 			true,
 			$this->forceType,
+			$this->forceAlternationBranchMatched,
+		);
+	}
+
+	/**
+	 * Unlike forceNonOptional(), the group stays optional when it is optional
+	 * within its alternation branch, e.g. because of a `?` quantifier.
+	 */
+	public function forceAlternationBranchMatched(): self
+	{
+		return new self(
+			$this->id,
+			$this->name,
+			$this->alternation,
+			$this->inOptionalQuantification,
+			$this->parent,
+			$this->type,
+			$this->forceNonOptional,
+			$this->forceType,
+			true,
 		);
 	}
 
@@ -50,6 +71,7 @@ public function forceType(Type $type): self
 			$type,
 			$this->forceNonOptional,
 			$this->forceType,
+			$this->forceAlternationBranchMatched,
 		);
 	}
 
@@ -64,6 +86,7 @@ public function withParent(RegexCapturingGroup|RegexNonCapturingGroup $parent):
 			$this->type,
 			$this->forceNonOptional,
 			$this->forceType,
+			$this->forceAlternationBranchMatched,
 		);
 	}
 
@@ -101,11 +124,32 @@ public function isOptional(): bool
 			return false;
 		}
 
+		if ($this->forceAlternationBranchMatched) {
+			return $this->isOptionalWithinAlternationBranch();
+		}
+
 		return $this->inAlternation()
 			|| $this->inOptionalQuantification
 			|| $this->parent !== null && $this->parent->isOptional();
 	}
 
+	private function isOptionalWithinAlternationBranch(): bool
+	{
+		if ($this->inOptionalQuantification) {
+			return true;
+		}
+
+		$parent = $this->parent;
+		while ($parent !== null && $parent->getAlternationId() === $this->getAlternationId()) {
+			if ($parent->inOptionalQuantification()) {
+				return true;
+			}
+			$parent = $parent->getParent();
+		}
+
+		return false;
+	}
+
 	public function inOptionalQuantification(): bool
 	{
 		return $this->inOptionalQuantification;

src/Type/Regex/RegexGroupList.php

@@ -48,13 +48,18 @@ public function forceGroupTypeAndNonOptional(RegexCapturingGroup $group, Type $t
 		return $this->cloneAndReParentList($group, $type);
 	}
 
-	private function cloneAndReParentList(RegexCapturingGroup $target, ?Type $type = null): self
+	public function forceGroupAlternationBranchMatched(RegexCapturingGroup $group): self
+	{
+		return $this->cloneAndReParentList($group, null, true);
+	}
+
+	private function cloneAndReParentList(RegexCapturingGroup $target, ?Type $type = null, bool $alternationBranchOnly = false): self
 	{
 		$groups = [];
 		$forcedGroup = null;
 		foreach ($this->groups as $i => $group) {
 			if ($group->getId() === $target->getId()) {
-				$forcedGroup = $group->forceNonOptional();
+				$forcedGroup = $alternationBranchOnly ? $group->forceAlternationBranchMatched() : $group->forceNonOptional();
 				if ($type !== null) {
 					$forcedGroup = $forcedGroup->forceType($type);
 				}

src/Type/Regex/RegexNonCapturingGroup.php

@@ -36,6 +36,11 @@ public function isOptional(): bool
 			|| ($this->parent !== null && $this->parent->isOptional());
 	}
 
+	public function inOptionalQuantification(): bool
+	{
+		return $this->inOptionalQuantification;
+	}
+
 	public function isTopLevel(): bool
 	{
 		return $this->parent === null

tests/PHPStan/Analyser/Bug15297Php73Test.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class Bug15297Php73Test extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/bug-15297-php73.php');
+	}
+
+	/**
+	 * @param mixed ...$args
+	 */
+	#[DataProvider('dataFileAsserts')]
+	public function testFileAsserts(
+		string $assertType,
+		string $file,
+		...$args,
+	): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/nodeScopeResolverPhp73.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/data/bug-15297-php73.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace Bug15297Php73;
+
+use function PHPStan\Testing\assertType;
+
+$pattern = "/^(?:
+	(?P<foo1>foo[a-z]+)
+	(?:-(?P<bar1>[0-9]+))?
+	|
+	(?P<foo2>foo[0-9]+)
+	(?:-(?P<bar2>[a-z]+))?
+)$/ix";
+if (preg_match($pattern, "foobar", $matches, \PREG_UNMATCHED_AS_NULL)) {
+	assertType("array{0: non-falsy-string, foo1: non-falsy-string, 1: non-falsy-string, bar1?: numeric-string, 2?: numeric-string}|array{0: non-falsy-string, foo1: null, 1: null, bar1: null, 2: null, foo2: non-falsy-string, 3: non-falsy-string, bar2?: non-empty-string, 4?: non-empty-string}", $matches);
+	$foo = $matches["foo1"] ?? $matches["foo2"] ?? "";
+	$bar = $matches["bar1"] ?? $matches["bar2"] ?? "";
+}
+
+function (string $s): void {
+	if (preg_match('/(a)?(b)?(c)/', $s, $matches, \PREG_UNMATCHED_AS_NULL)) {
+		assertType("array{non-falsy-string, 'a'|null, 'b'|null, 'c'}", $matches);
+	}
+	if (preg_match('/(a)(b)?(c)?/', $s, $matches, \PREG_UNMATCHED_AS_NULL)) {
+		assertType("list{0: non-falsy-string, 1: 'a', 2?: 'b'|null, 3?: 'c'}", $matches);
+	}
+};

tests/PHPStan/Analyser/nodeScopeResolverPhp73.neon

@@ -0,0 +1,2 @@
+parameters:
+	phpVersion: 70300 # PHP 7.3

tests/PHPStan/Analyser/nsrt/bug-15297.php

@@ -0,0 +1,26 @@
+<?php declare(strict_types = 1);
+
+namespace Bug15297;
+
+use function PHPStan\Testing\assertType;
+
+function doFoo(string $s): void
+{
+	$pattern = "/^(?:
+	(?P<foo1>foo[a-z]+)
+	(?:-(?P<bar1>[0-9]+))?
+	|
+	(?P<foo2>foo[0-9]+)
+	(?:-(?P<bar2>[a-z]+))?
+)$/ix";
+	if (preg_match($pattern, $s, $matches)) {
+		assertType("array{0: non-falsy-string, foo1: '', 1: '', bar1: '', 2: '', foo2: non-falsy-string, 3: non-falsy-string, bar2?: non-empty-string, 4?: non-empty-string}|array{0: non-falsy-string, foo1: non-falsy-string, 1: non-falsy-string, bar1?: numeric-string, 2?: numeric-string}", $matches);
+	}
+}
+
+function doBar(string $s): void
+{
+	if (preg_match('/^(?:(?:(a))?(b)|(c))$/', $s, $matches)) {
+		assertType("array{non-falsy-string, '', '', 'c'}|list{0: non-falsy-string, 1?: ''|'a', 2: 'b'}", $matches);
+	}
+}

tests/PHPStan/Rules/Variables/NullCoalesceRulePhp73Test.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Variables;
+
+use PHPStan\Rules\Comparison\ConstantConditionInTraitHelper;
+use PHPStan\Rules\IssetCheck;
+use PHPStan\Rules\Properties\PropertyDescriptor;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<NullCoalesceRule>
+ */
+class NullCoalesceRulePhp73Test extends RuleTestCase
+{
+
+	protected function getRule(): Rule
+	{
+		return new NullCoalesceRule(
+			new IssetCheck(
+				new PropertyDescriptor(),
+				true,
+				$this->shouldTreatPhpDocTypesAsCertain(),
+			),
+			self::getContainer()->getByType(ConstantConditionInTraitHelper::class),
+			true,
+		);
+	}
+
+	public function testBug15297(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-15297.php'], [
+			[
+				'Offset \'foo2\' on array{0: non-falsy-string, foo1: null, 1: null, bar1: null, 2: null, foo2: non-falsy-string, 3: non-falsy-string, bar2?: non-empty-string, ...} on left side of ?? always exists and is not nullable.',
+				11,
+			],
+		]);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/data/null-coalesce-php73.neon',
+		];
+	}
+
+}

tests/PHPStan/Rules/Variables/data/bug-15297.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types = 1);
+
+$pattern = "/^(?:
+	(?P<foo1>foo[a-z]+)
+	(?:-(?P<bar1>[0-9]+))?
+	|
+	(?P<foo2>foo[0-9]+)
+	(?:-(?P<bar2>[a-z]+))?
+)$/ix";
+if (preg_match($pattern, "foobar", $matches, \PREG_UNMATCHED_AS_NULL)) {
+	$foo = $matches["foo1"] ?? $matches["foo2"] ?? "";
+	$bar = $matches["bar1"] ?? $matches["bar2"] ?? "";
+}