Merge branch 2.1.x into 2.2.x

Author: phpstan-bot

CLAUDE.md

@@ -240,11 +240,36 @@ Historical analysis of `Type.php` via `git blame` shows that new methods are add
 
 When considering a bug fix that involves checking "is this type a Foo?", first check whether an appropriate method already exists on `Type`. If not, consider whether adding one would be the right fix — especially if the check is needed in more than one place or involves logic that varies by type class.
 
+### Type system: never sort, compare, or transform types via `describe()`
+
+`describe()` is for human-readable error messages, not for ordering or matching. To sort the keys of a `ConstantArrayType`, sort the underlying key `Type` objects (introduce a new method on `ConstantArrayType` if needed) — never `usort()` on `describe()` output. To compare types, use `equals()`, `isSuperTypeOf()`, or `accepts()`, not `describe() === describe()`. String-manipulating type descriptions is a recurring red flag.
+
+### Performance fixes: solve the algorithm, not the limit
+
+When PHPStan is slow on a case, do not "fix" it by lowering or introducing a hard cap on iterations, recursion depth, fan-out, or array size. Find the algorithmic root cause first. It is fine to *temporarily* raise an existing limit to make the slowness visible during investigation — but restore the original limit once the algorithmic fix lands. Limits are last-resort safety nets, not fixes. Dumbing down analysis to make a benchmark pass is not acceptable.
+
+### Don't refactor code under analysis — make PHPStan smarter
+
+When `make phpstan` flags PHPStan's own source, or when an issue's playground sample reproduces a bug, the default fix is to teach inference to handle the original code, not to rewrite the code. The same applies to regression test data: copy the reproducer from the issue's playground link as close to verbatim as practical, and once the test fails for the right reason, do not simplify or rephrase it.
+
+### After fixing one bug, look for the same bug in adjacent code
+
+Bugs in PHPStan's type system rarely live alone. A fix in one accessory type usually has counterparts in the other accessory types. A fix in property handling often has analogues in methods and class constants. A fix at one call site of a `Type` API often repeats at other call sites. After landing a fix, actively scan the parallel code paths (sibling `*Type` classes, the same trait, the same dispatch table, all callers of the changed API) and try to reproduce and fix the pattern there too — each with its own failing test.
+
+### Magic numbers belong in named `_LIMIT` constants
+
+Every threshold, fan-out cap, recursion bound, or collection-size limit must be a class constant whose name ends in `_LIMIT`, declared at the top of the owning class. Inline numerics in conditionals (`if (count($this->optionalKeys) <= 10)`) are not acceptable — extract to `self::OPTIONAL_KEYS_LIMIT` (or similar) so the threshold is named, discoverable, and tunable in one place.
+
 ### Testing patterns
 
 - **Rule tests**: Extend `RuleTestCase`, implement `getRule()`, call `$this->analyse([__DIR__ . '/data/my-test.php'], [...expected errors...])`. Expected errors are `[message, line]` pairs. Test data files live in `tests/PHPStan/Rules/*/data/`.
 - **Type inference tests**: Use `assertType()` and `assertNativeType()` helper functions in test data files. The test runner verifies PHPStan infers the declared types at each `assertType()` call.
-- **Regression tests**: For each bug fix, add a test data file reproducing the issue (e.g. `tests/PHPStan/Rules/*/data/bug-12345.php` or `tests/PHPStan/Analyser/nsrt/bug-12345.php`).
+- **Choosing the test home for a regression**: pick by what the bug is about.
+  - *Wrong inferred type / missing narrowing* → `tests/PHPStan/Analyser/nsrt/bug-<n>.php` with `assertType()` calls.
+  - *Rule reports a wrong/missing error* → `tests/PHPStan/Rules/<Category>/data/bug-<n>.php` plus expectations in the rule's test class.
+  - If the bug touches both, add both.
+- **Always verify the test fails before the fix.** Stating "tests pass" is not enough — that only proves the fix doesn't break things. `git stash` the source change, run the test, see it fail for the right reason; `git stash pop`, run again, see it pass. Only then is the fix confirmed. The `regression-test` skill bakes this in for bug-issue workflows.
+- **Reproducers come from the OP's playground link** in the issue body, not from later comments. Copy the snippet as close to verbatim as practical.
 - **Integration tests**: `AnalyserIntegrationTest` runs full analysis on test files and checks error output.
 
 ### Adding support for new PHP versions
@@ -259,6 +284,14 @@ Recent work on PHP 8.5 support shows the pattern:
 - **PhpVersion**: Add detection methods like `supportsPropertyHooks()`, `supportsPipeOperator()`, etc.
 - **Stubs**: Update function/class stubs for new built-in functions and changed signatures
 
+## Workflow for bug fixes
+
+- **One fix, one commit (or one PR)**. Bench scripts and tests for a fix go in the same commit as the source change, not separately.
+- **Commit messages and PR titles describe the change, not the bug they close.** Prefer "Do not subtract TemplateType from TemplateType" over "Fix #14459: type subtraction". Issue closure goes in the PR body via `Closes https://github.com/phpstan/phpstan/issues/<n>`.
+- **Standard reproducer command**: `bin/phpstan analyse -l 8 <file> --debug` (add `-vvv` for hangs and infinite loops). Files under `tests/bench/data` are not directly runnable as PHPStan inputs — copy the reproducing snippet into a `test.php` at the repo root first, then analyse that.
+- **Debug helpers in analysed code**: `\PHPStan\dumpType($expr)` prints the inferred type of an expression at that point; `\PHPStan\debugScope()` prints the current scope. Inside `NodeScopeResolver` itself, `var_dump($scope->debug())` is the canonical inspection point. Reach for these before guessing what PHPStan is doing.
+- **When the user says "I don't understand why X is needed"** about existing code, treat it as a request to investigate whether X is actually needed — not a request to defend the status quo. The answer is often that two paths can be unified or one block deleted.
+
 ## Writing PHPDocs
 
 When adding or editing PHPDoc comments in this codebase, follow these guidelines:

src/Type/Constant/ConstantArrayType.php

@@ -101,7 +101,7 @@ class ConstantArrayType implements Type
 	 * @api
 	 * @param list<ConstantIntegerType|ConstantStringType> $keyTypes
 	 * @param array<int, Type> $valueTypes
-	 * @param non-empty-list<int> $nextAutoIndexes
+	 * @param list<int> $nextAutoIndexes
 	 * @param int[] $optionalKeys
 	 */
 	public function __construct(
@@ -128,7 +128,7 @@ public function __construct(
 	/**
 	 * @param list<ConstantIntegerType|ConstantStringType> $keyTypes
 	 * @param array<int, Type> $valueTypes
-	 * @param non-empty-list<int> $nextAutoIndexes
+	 * @param list<int> $nextAutoIndexes
 	 * @param int[] $optionalKeys
 	 */
 	protected function recreate(
@@ -208,7 +208,7 @@ public function isConstantValue(): TrinaryLogic
 	}
 
 	/**
-	 * @return non-empty-list<int>
+	 * @return list<int>
 	 */
 	public function getNextAutoIndexes(): array
 	{
@@ -745,6 +745,10 @@ public function getOffsetValueType(Type $offsetType): Type
 
 	public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $unionValues = true): Type
 	{
+		if ($offsetType === null && count($this->nextAutoIndexes) === 0) {
+			return new ErrorType();
+		}
+
 		$builder = ConstantArrayTypeBuilder::createFromConstantArray($this);
 		$builder->setOffsetValueType($offsetType, $valueType);
 

src/Type/Constant/ConstantArrayTypeBuilder.php

@@ -44,7 +44,7 @@ final class ConstantArrayTypeBuilder
 	/**
 	 * @param list<Type> $keyTypes
 	 * @param array<int, Type> $valueTypes
-	 * @param non-empty-list<int> $nextAutoIndexes
+	 * @param list<int> $nextAutoIndexes
 	 * @param array<int> $optionalKeys
 	 */
 	private function __construct(
@@ -85,6 +85,10 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 			$offsetType = $offsetType->toArrayKey();
 		}
 
+		if ($offsetType === null && count($this->nextAutoIndexes) === 0) {
+			return;
+		}
+
 		if (!$this->degradeToGeneralArray) {
 			if (
 				$valueType instanceof ClosureType
@@ -108,6 +112,10 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 			}
 
 			if ($offsetType === null) {
+				if (count($this->nextAutoIndexes) === 0) {
+					return;
+				}
+
 				$newAutoIndexes = $optional ? $this->nextAutoIndexes : [];
 				$hasOptional = false;
 				foreach ($this->keyTypes as $i => $keyType) {
@@ -127,11 +135,10 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 
 					/** @var int|float $newAutoIndex */
 					$newAutoIndex = $keyType->getValue() + 1;
-					if (is_float($newAutoIndex)) {
-						$newAutoIndex = $keyType->getValue();
+					if (!is_float($newAutoIndex)) {
+						$newAutoIndexes[] = $newAutoIndex;
 					}
 
-					$newAutoIndexes[] = $newAutoIndex;
 					$hasOptional = true;
 				}
 
@@ -142,11 +149,10 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 
 				/** @var int|float $newAutoIndex */
 				$newAutoIndex = $max + 1;
-				if (is_float($newAutoIndex)) {
-					$newAutoIndex = $max;
+				if (!is_float($newAutoIndex)) {
+					$newAutoIndexes[] = $newAutoIndex;
 				}
 
-				$newAutoIndexes[] = $newAutoIndex;
 				$this->nextAutoIndexes = array_values(array_unique($newAutoIndexes));
 
 				if ($optional || $hasOptional) {
@@ -180,11 +186,7 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 					if (!$optional) {
 						$this->optionalKeys = array_values(array_filter($this->optionalKeys, static fn (int $index): bool => $index !== $i));
 						if ($keyType instanceof ConstantIntegerType) {
-							$nextAutoIndexes = array_values(array_filter($this->nextAutoIndexes, static fn (int $index) => $index > $keyType->getValue()));
-							if (count($nextAutoIndexes) === 0) {
-								throw new ShouldNotHappenException();
-							}
-							$this->nextAutoIndexes = $nextAutoIndexes;
+							$this->nextAutoIndexes = array_values(array_filter($this->nextAutoIndexes, static fn (int $index) => $index > $keyType->getValue()));
 						}
 					}
 					return;
@@ -194,33 +196,38 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 				$this->valueTypes[] = $valueType;
 
 				if ($offsetType instanceof ConstantIntegerType) {
-					$min = min($this->nextAutoIndexes);
-					$max = max($this->nextAutoIndexes);
-					$offsetValue = $offsetType->getValue();
-					if ($offsetValue >= 0) {
-						if ($offsetValue > $min) {
-							if ($offsetValue <= $max) {
-								$this->isList = $this->isList->and(TrinaryLogic::createMaybe());
+					if (count($this->nextAutoIndexes) > 0) {
+						$min = min($this->nextAutoIndexes);
+						$max = max($this->nextAutoIndexes);
+						$offsetValue = $offsetType->getValue();
+						if ($offsetValue >= 0) {
+							if ($offsetValue > $min) {
+								if ($offsetValue <= $max) {
+									$this->isList = $this->isList->and(TrinaryLogic::createMaybe());
+								} else {
+									$this->isList = TrinaryLogic::createNo();
+								}
+							}
+						} else {
+							$this->isList = TrinaryLogic::createNo();
+						}
+
+						if ($offsetValue >= $max) {
+							/** @var int|float $newAutoIndex */
+							$newAutoIndex = $offsetValue + 1;
+							if (is_float($newAutoIndex)) {
+								if (!$optional) {
+									$this->nextAutoIndexes = [];
+								}
+							} elseif (!$optional) {
+								$this->nextAutoIndexes = [$newAutoIndex];
 							} else {
-								$this->isList = TrinaryLogic::createNo();
+								$this->nextAutoIndexes[] = $newAutoIndex;
 							}
 						}
 					} else {
 						$this->isList = TrinaryLogic::createNo();
 					}
-
-					if ($offsetValue >= $max) {
-						/** @var int|float $newAutoIndex */
-						$newAutoIndex = $offsetValue + 1;
-						if (is_float($newAutoIndex)) {
-							$newAutoIndex = $max;
-						}
-						if (!$optional) {
-							$this->nextAutoIndexes = [$newAutoIndex];
-						} else {
-							$this->nextAutoIndexes[] = $newAutoIndex;
-						}
-					}
 				} else {
 					$this->isList = TrinaryLogic::createNo();
 				}
@@ -300,6 +307,10 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 							continue;
 						}
 
+						if (count($this->nextAutoIndexes) === 0) {
+							continue;
+						}
+
 						$max = max($this->nextAutoIndexes);
 						$offsetValue = $scalarType->getValue();
 						if ($offsetValue < $max) {
@@ -309,7 +320,7 @@ public function setOffsetValueType(?Type $offsetType, Type $valueType, bool $opt
 						/** @var int|float $newAutoIndex */
 						$newAutoIndex = $offsetValue + 1;
 						if (is_float($newAutoIndex)) {
-							$newAutoIndex = $max;
+							continue;
 						}
 						$this->nextAutoIndexes[] = $newAutoIndex;
 					}

src/Type/Generic/TemplateConstantArrayType.php

@@ -4,8 +4,6 @@
 
 use PHPStan\TrinaryLogic;
 use PHPStan\Type\Constant\ConstantArrayType;
-use PHPStan\Type\Constant\ConstantIntegerType;
-use PHPStan\Type\Constant\ConstantStringType;
 use PHPStan\Type\Traits\UndecidedComparisonCompoundTypeTrait;
 use PHPStan\Type\Type;
 
@@ -38,12 +36,6 @@ public function __construct(
 		$this->default = $default;
 	}
 
-	/**
-	 * @param list<ConstantIntegerType|ConstantStringType> $keyTypes
-	 * @param array<int, Type> $valueTypes
-	 * @param non-empty-list<int> $nextAutoIndexes
-	 * @param int[] $optionalKeys
-	 */
 	protected function recreate(
 		array $keyTypes,
 		array $valueTypes,

tests/PHPStan/Analyser/AnalyserIntegrationTest.php

@@ -164,6 +164,12 @@ public function testExtendsPdoStatementCrash(): void
 		$this->assertNoErrors($errors);
 	}
 
+	public function testBug14548(): void
+	{
+		$errors = $this->runAnalyse(__DIR__ . '/data/bug-14548.php');
+		$this->assertNoErrors($errors);
+	}
+
 	public function testBug12803(): void
 	{
 		// crash

tests/PHPStan/Analyser/data/bug-14548.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Bug14548;
+
+class TProcessHelper
+{
+
+	public static function setProcessPriority(int $priority): void
+	{
+		$priorityValues = [ // The priority cap to windows text priority.
+			-15 => 24,
+			-10 => 13,
+			-5 => 10,
+			4 => 8,
+			9 => 6,
+			PHP_INT_MAX => 4,
+		];
+		foreach ($priorityValues as $keyPriority => $priorityName) {
+			if ($priority <= $keyPriority) {
+				break;
+			}
+		}
+	}
+}

tests/PHPStan/Rules/Arrays/OffsetAccessAssignmentRuleTest.php

@@ -207,4 +207,19 @@ public function testBug8648(): void
 		$this->analyse([__DIR__ . '/data/bug-8648.php'], []);
 	}
 
+	public function testAppendToArrayWithPhpIntMaxKey(): void
+	{
+		$this->checkUnionTypes = true;
+		$this->analyse([__DIR__ . '/data/offset-access-assignment-php-int-max.php'], [
+			[
+				'Cannot assign new offset to array<int, int>.',
+				9,
+			],
+			[
+				'Cannot assign new offset to array<int, int>.',
+				15,
+			],
+		]);
+	}
+
 }

tests/PHPStan/Rules/Arrays/data/offset-access-assignment-php-int-max.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types = 1);
+
+namespace OffsetAccessAssignmentPhpIntMax;
+
+function (): void {
+	$a = [
+		9223372036854775807 => 4,
+	];
+	$a[] = 5;
+};
+
+function (): void {
+	$a = [];
+	$a[9223372036854775807] = 4;
+	$a[] = 5;
+};
+
+function (): void {
+	$a = [
+		9223372036854775807 => 4,
+	];
+	$a[10] = 5;
+};