Merge test files and add reviewer's constant array test case

- Merge bug-1311-constant-array.php into bug-1311.php (single file, single namespace)
- Merge bug-1940-with-key.php into bug-1940.php (single file, single namespace)
- Add test for constant array by-ref foreach with sub-element modification
  to verify no false positive about missing offset after mutations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phpstan-bot

tests/PHPStan/Analyser/nsrt/bug-1311-constant-array.php

@@ -24,4 +24,124 @@ public function convertList(array $temp): void
 
 		$this->list = $temp;
 	}
+
+	public function convertListByRefWithoutKey(): void
+	{
+		$temp = [1, 2, 3];
+
+		foreach ($temp as &$item) {
+			$item = (string) $item;
+		}
+
+		assertType("array{'1'|'2'|'3', '1'|'2'|'3', '1'|'2'|'3'}", $temp);
+
+		$this->list = $temp;
+	}
+
+	public function convertListByRefWithKey(): void
+	{
+		$temp = [1, 2, 3];
+
+		foreach ($temp as $k => &$item) {
+			$item = (string) $item;
+		}
+
+		assertType("array{'1'|'2'|'3', '1'|'2'|'3', '1'|'2'|'3'}", $temp);
+
+		$this->list = $temp;
+	}
+
+	public function byRefConstantArrayConditional(): void
+	{
+		$temp = [1, 2, 3];
+
+		foreach ($temp as &$item) {
+			if (rand(0, 1)) {
+				$item = (string) $item;
+			}
+		}
+
+		assertType("array{1|2|3|'1'|'2'|'3', 1|2|3|'1'|'2'|'3', 1|2|3|'1'|'2'|'3'}", $temp);
+	}
+
+	public function byRefConstantArrayWithBreak(): void
+	{
+		$temp = [1, 2, 3];
+
+		foreach ($temp as &$item) {
+			$item = (string) $item;
+			if (rand(0, 1)) {
+				break;
+			}
+		}
+
+		assertType('array{1, 2, 3}', $temp);
+	}
+
+	public function byRefConstantArrayIntval(): void
+	{
+		$temp = ['a', 'b', 'c'];
+
+		foreach ($temp as &$item) {
+			$item = strlen($item);
+		}
+
+		assertType('array{1, 1, 1}', $temp);
+	}
+
+	public function byRefConstantArrayStringKeys(): void
+	{
+		$temp = ['x' => 1, 'y' => 2];
+
+		foreach ($temp as &$v) {
+			$v = (string) $v;
+		}
+
+		assertType("array{x: '1'|'2', y: '1'|'2'}", $temp);
+	}
+
+	public function byRefConstantArrayNoOverwrite(): void
+	{
+		$temp = [1, 2, 3];
+
+		foreach ($temp as &$item) {
+			echo $item;
+		}
+
+		assertType('array{1, 2, 3}', $temp);
+	}
+
+	public function constantArrayByRefSubElement(): void
+	{
+		$a = [
+			[
+				'one' => 'one',
+				'two' => 'two',
+			],
+			[
+				'one' => 'one',
+			],
+		];
+
+		foreach ($a as &$testArray) {
+			$testArray['two'] = 'two';
+		}
+		unset($testArray);
+
+		assertType("array{array{one: 'one', two: 'two'}, array{one: 'one', two: 'two'}}", $a);
+
+		$key = 'three';
+
+		foreach ($a as $offset => $testArray) {
+			$a[$offset][$key] = $key;
+		}
+
+		assertType("array{array{one: 'one', two: 'two', three: 'three'}, array{one: 'one', two: 'two', three: 'three'}}", $a);
+
+		foreach ($a as $testArray) {
+			assertType("array{one: 'one', two: 'two', three: 'three'}", $testArray);
+			$testArray['two'];
+			$testArray['three'];
+		}
+	}
 }

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

@@ -83,7 +83,6 @@ function byRefWithoutKeyNonEmpty(array $arr): void
 }
 
 /**
- * By-ref without key with break — should NOT rewrite since not all elements may be visited.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyBreak(array $arr): void
@@ -99,7 +98,6 @@ function byRefWithoutKeyBreak(array $arr): void
 }
 
 /**
- * By-ref without key with continue — should still rewrite since all elements are visited.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyContinue(array $arr): void
@@ -115,7 +113,6 @@ function byRefWithoutKeyContinue(array $arr): void
 }
 
 /**
- * By-ref without key with continue where value is overwritten in all branches.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyContinueBranches(array $arr): void
@@ -132,7 +129,6 @@ function byRefWithoutKeyContinueBranches(array $arr): void
 }
 
 /**
- * By-ref without key with continue where value is NOT overwritten in the continue branch.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyContinuePartial(array $arr): void
@@ -152,9 +148,6 @@ class Foo
 	/** @var array<string, int> */
 	private array $prop;
 
-	/**
-	 * By-ref without key on a property.
-	 */
 	public function byRefWithoutKeyProperty(): void
 	{
 		foreach ($this->prop as &$v) {
@@ -166,7 +159,6 @@ public function byRefWithoutKeyProperty(): void
 }
 
 /**
- * By-ref without key with intval transformation.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyTransform(array $arr): void
@@ -179,15 +171,61 @@ function byRefWithoutKeyTransform(array $arr): void
 }
 
 /**
- * By-ref without key — value not overwritten at all.
  * @param array<int, string> $arr
  */
 function byRefWithoutKeyNoOverwrite(array $arr): void
 {
 	foreach ($arr as &$v) {
-		// just read, don't write
 		echo $v;
 	}
 
 	assertType('array<int, string>', $arr);
 }
+
+/**
+ * @param list<array{one: string}> $a
+ */
+function byRefWithKeyModifySubElement(array $a): void
+{
+	foreach ($a as $k => &$testArray) {
+		$testArray['two'] = 'two';
+	}
+
+	assertType("list<array{one: string, two: 'two'}>", $a);
+}
+
+/**
+ * @param list<array{one: string}> $a
+ */
+function byRefWithoutKeyModifySubElement(array $a): void
+{
+	foreach ($a as &$testArray) {
+		$testArray['two'] = 'two';
+	}
+
+	assertType("list<array{one: string, two: 'two'}>", $a);
+}
+
+/**
+ * @param array<int, string> $arr
+ */
+function byRefWithKeyDirectOverwrite(array $arr): void
+{
+	foreach ($arr as $k => &$v) {
+		$v = 1;
+	}
+
+	assertType('array<int, 1>', $arr);
+}
+
+/**
+ * @param array<int, string> $arr
+ */
+function byRefWithoutKeyDirectOverwrite(array $arr): void
+{
+	foreach ($arr as &$v) {
+		$v = 1;
+	}
+
+	assertType('array<int, 1>', $arr);
+}