Collect template argument constraints through object shape properties in TemplateArgumentObserver

- TemplateArgumentObserver::observeSend() now matches a declared `object{...}`
  shape property by property against the actual object's public non-static
  properties (new observeObjectShapeSend()). Before, a declared shape names no
  class, so `(object) ['x' => new Collection([...])]` returned or passed as
  `object{x: Collection<int, string>}` never constrained the inner `new`
  site, and its invariant TKey stayed at the exact `0|1|...` literal.
- A declared intersection `object{...}&Foo` sends to each shape member too.
- Ported the same logic to the native mirror in
  turbo-ext/src/TemplateArgumentObserver.cpp and regenerated its declarations
  header.
- Covers every place that sends to a declared type: return, typed property
  assignment, call argument and `yield` (Generator value type), plus nested
  shapes, nullable unions and optional shape properties.
- Probed and left alone: closures returned as `Closure(): object{...}` do not
  constrain their body's `new` sites even with plain generic or array shape
  return types. That limitation is separate from object shapes.

Author: phpstan-bot

phpstan-baseline.neon

@@ -54,6 +54,18 @@ parameters:
 			count: 1
 			path: src/Analyser/ExprHandler/Helper/IncDecTypeHelper.php
 
+		-
+			rawMessage: Doing instanceof PHPStan\Type\IntersectionType is error-prone and deprecated.
+			identifier: phpstanApi.instanceofType
+			count: 1
+			path: src/Analyser/Generics/TemplateArgumentObserver.php
+
+		-
+			rawMessage: 'Doing instanceof PHPStan\Type\ObjectShapeType is error-prone and deprecated. Use Type::isObject() and Type::hasProperty() instead.'
+			identifier: phpstanApi.instanceofType
+			count: 2
+			path: src/Analyser/Generics/TemplateArgumentObserver.php
+
 		-
 			rawMessage: Casting to string something that's already string.
 			identifier: cast.useless

src/Analyser/Generics/TemplateArgumentObserver.php

@@ -5,6 +5,7 @@
 use PhpParser\Node\Expr;
 use PHPStan\Analyser\OutOfClassScope;
 use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Reflection\MissingPropertyFromReflectionException;
 use PHPStan\Reflection\ParametersAcceptor;
 use PHPStan\Reflection\ResolvedFunctionVariant;
 use PHPStan\Turbo\ShadowedByTurboExtension;
@@ -14,8 +15,10 @@
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\Generic\UnresolvedTemplateArgumentType;
+use PHPStan\Type\IntersectionType;
 use PHPStan\Type\MixedType;
 use PHPStan\Type\NeverType;
+use PHPStan\Type\ObjectShapeType;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
 use PHPStan\Type\TypeTraverser;
@@ -451,6 +454,18 @@ private function observeSend(TemplateArgumentConstraints $constraints, Type $dec
 			// never holds no markers, and is its own iterable key and value type
 			return $constraints;
 		}
+		if ($declared instanceof ObjectShapeType) {
+			return $this->observeObjectShapeSend($constraints, $declared, $actual, $isCallArgument);
+		}
+		if ($declared instanceof IntersectionType) {
+			// object{...}&Foo - the shape's properties are bounds next to Foo's arguments
+			foreach ($declared->getTypes() as $member) {
+				if (!$member instanceof ObjectShapeType) {
+					continue;
+				}
+				$constraints = $this->observeObjectShapeSend($constraints, $member, $actual, $isCallArgument);
+			}
+		}
 
 		$actualReflections = $actual->getObjectClassReflections();
 		if (count($actualReflections) === 1) {
@@ -506,6 +521,38 @@ private function observeSend(TemplateArgumentConstraints $constraints, Type $dec
 		return $constraints;
 	}
 
+	/**
+	 * Each property of the object flows into the declared property of the shape
+	 * (`(object) ['x' => new Foo(1)]` returned as `object{x: Foo<int>}`).
+	 */
+	private function observeObjectShapeSend(TemplateArgumentConstraints $constraints, ObjectShapeType $declared, Type $actual, bool $isCallArgument): TemplateArgumentConstraints
+	{
+		if (!$actual->isObject()->yes()) {
+			return $constraints;
+		}
+
+		$scope = new OutOfClassScope();
+		foreach ($declared->getProperties() as $name => $declaredPropertyType) {
+			$name = (string) $name;
+			if (!$actual->hasInstanceProperty($name)->yes()) {
+				continue;
+			}
+
+			try {
+				$actualProperty = $actual->getInstanceProperty($name, $scope);
+			} catch (MissingPropertyFromReflectionException) {
+				continue;
+			}
+			if (!$actualProperty->isPublic() || $actualProperty->isStatic()) {
+				continue;
+			}
+
+			$constraints = $this->observeSend($constraints, $declaredPropertyType, $actualProperty->getReadableType(), $isCallArgument);
+		}
+
+		return $constraints;
+	}
+
 	/**
 	 * A template argument of an object sent to the declared argument at the same
 	 * position. A union of several sites' markers (Box<T|U> of zip(of(1), of(2)))

tests/PHPStan/Rules/Generators/YieldTypeRuleTest.php

@@ -87,4 +87,9 @@ public function testYieldOversizedSelfRejection(): void
 		$this->analyse([__DIR__ . '/data/bug-yield-oversized-self-rejection.php'], []);
 	}
 
+	public function testBug15417(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-15417.php'], []);
+	}
+
 }

tests/PHPStan/Rules/Generators/data/bug-15417.php

@@ -0,0 +1,24 @@
+<?php declare(strict_types = 1);
+
+namespace Bug15417Generator;
+
+/**
+ * @template TKey of array-key
+ * @template-covariant TValue
+ */
+final class Collection
+{
+	/** @param iterable<TKey, TValue> $a */
+	public function __construct($a) { }
+}
+
+final class Repro
+{
+
+	/** @return \Generator<int, object{x: Collection<int, string>}> */
+	public static function gen(): \Generator
+	{
+		yield (object) ['x' => new Collection(['a', 'b'])];
+	}
+
+}

tests/PHPStan/Rules/Methods/CallStaticMethodsRuleTest.php

@@ -1156,4 +1156,10 @@ public function testBug11421(): void
 		]);
 	}
 
+	public function testBug15417(): void
+	{
+		$this->checkThisOnly = false;
+		$this->analyse([__DIR__ . '/data/bug-15417-argument.php'], []);
+	}
+
 }

tests/PHPStan/Rules/Methods/ReturnTypeRuleTest.php

@@ -1420,4 +1420,21 @@ public function testBug13325(): void
 		$this->analyse([__DIR__ . '/data/bug-13325.php'], []);
 	}
 
+	#[RequiresPhp('>= 8.2.0')]
+	public function testBug15417(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-15417.php'], []);
+	}
+
+	public function testBug15417Shapes(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-15417-shapes.php'], [
+			[
+				'Method Bug15417Shapes\\Repro::stillReported() should return object{x: Bug15417Shapes\\Collection<string, string>} but returns object{x: Bug15417Shapes\\Collection<0|1, \'a\'|\'b\'>}&stdClass.',
+				51,
+				'Property ($x) type Bug15417Shapes\\Collection<string, string> does not accept type Bug15417Shapes\\Collection<0|1, \'a\'|\'b\'>.',
+			],
+		]);
+	}
+
 }

tests/PHPStan/Rules/Methods/data/bug-15417-argument.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace Bug15417Argument;
+
+/**
+ * @template TKey of array-key
+ * @template-covariant TValue
+ */
+final class Collection
+{
+	/** @param iterable<TKey, TValue> $a */
+	public function __construct($a) { }
+}
+
+final class Repro
+{
+
+	/** @param object{x: Collection<int, string>} $o */
+	public static function take(object $o): void
+	{
+	}
+
+	public static function doFoo(): void
+	{
+		self::take((object) ['x' => new Collection(['a', 'b'])]);
+	}
+
+}

tests/PHPStan/Rules/Methods/data/bug-15417-shapes.php

@@ -0,0 +1,54 @@
+<?php declare(strict_types = 1);
+
+namespace Bug15417Shapes;
+
+/**
+ * @template TKey of array-key
+ * @template-covariant TValue
+ */
+final class Collection
+{
+	/** @param iterable<TKey, TValue> $a */
+	public function __construct($a) { }
+}
+
+final class Repro
+{
+
+	/** @return object{x: Collection<int, string>} */
+	public static function shape(): object
+	{
+		return (object) ['x' => new Collection(['a', 'b'])];
+	}
+
+	/** @return object{y: object{x: Collection<int, string>}} */
+	public static function nested(): object
+	{
+		return (object) ['y' => (object) ['x' => new Collection(['a', 'b'])]];
+	}
+
+	/** @return object{x: Collection<int, string>}|null */
+	public static function nullable(bool $b): ?object
+	{
+		return $b ? (object) ['x' => new Collection(['a', 'b'])] : null;
+	}
+
+	/** @return object{x: Collection<int, string>}&\stdClass */
+	public static function intersection(): object
+	{
+		return (object) ['x' => new Collection(['a', 'b'])];
+	}
+
+	/** @return list<object{x: Collection<int, string>, y?: Collection<int, int>}> */
+	public static function optional(): array
+	{
+		return [(object) ['x' => new Collection(['a', 'b'])]];
+	}
+
+	/** @return object{x: Collection<string, string>} */
+	public static function stillReported(): object
+	{
+		return (object) ['x' => new Collection(['a', 'b'])];
+	}
+
+}

tests/PHPStan/Rules/Methods/data/bug-15417.php

@@ -0,0 +1,33 @@
+<?php // lint >= 8.2
+
+declare(strict_types = 1);
+
+namespace Bug15417;
+
+class Repro
+{
+	/** @return Collection<int, object{ch: string, x: Collection<int, object{t: string}>}> */
+	public static function get(string $s): Collection
+	{
+		$data = [];
+		foreach (explode(',', $s) as $char) {
+			$c = array_map(fn($x) => (object)['t' => $x], ['a', 'b', 'c', 'd']);
+			if ($s !== 'z') {
+				$data[] = (object)['ch' => $char, 'x' => new Collection((new \Random\Randomizer)->shuffleArray($c))];
+			}
+		}
+
+		return new Collection($data);
+	}
+}
+
+/**
+ * @template TKey of array-key
+ * @template-covariant TValue (THEA fix by FixLarastanStubs.php)
+ */
+class Collection
+{
+	/** @param iterable<TKey, TValue> $a */
+	public function __construct($a) { echo gettype($a); }
+}
+

tests/PHPStan/Rules/Properties/TypesAssignedToPropertiesRuleTest.php

@@ -1145,4 +1145,9 @@ public function testIntersectionWithTemplateMixed(): void
 		]);
 	}
 
+	public function testBug15417(): void
+	{
+		$this->analyse([__DIR__ . '/data/bug-15417.php'], []);
+	}
+
 }