Fix phpstan/phpstan#9634: Cannot use "T is never" in conditional return (#5082)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

src/Type/NeverType.php

@@ -14,6 +14,7 @@
 use PHPStan\ShouldNotHappenException;
 use PHPStan\TrinaryLogic;
 use PHPStan\Type\Enum\EnumCaseObjectType;
+use PHPStan\Type\Generic\TemplateType;
 use PHPStan\Type\Traits\NonGeneralizableTypeTrait;
 use PHPStan\Type\Traits\NonGenericTypeTrait;
 use PHPStan\Type\Traits\NonRemoveableTypeTrait;
@@ -81,6 +82,10 @@ public function isSuperTypeOf(Type $type): IsSuperTypeOfResult
 			return IsSuperTypeOfResult::createYes();
 		}
 
+		if ($type instanceof TemplateType) {
+			return IsSuperTypeOfResult::createMaybe();
+		}
+
 		return IsSuperTypeOfResult::createNo();
 	}
 

src/Type/NonAcceptingNeverType.php

@@ -2,6 +2,8 @@
 
 namespace PHPStan\Type;
 
+use PHPStan\Type\Generic\TemplateType;
+
 /** @api */
 class NonAcceptingNeverType extends NeverType
 {
@@ -21,6 +23,10 @@ public function isSuperTypeOf(Type $type): IsSuperTypeOfResult
 			return IsSuperTypeOfResult::createMaybe();
 		}
 
+		if ($type instanceof TemplateType) {
+			return IsSuperTypeOfResult::createMaybe();
+		}
+
 		return IsSuperTypeOfResult::createNo();
 	}
 

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

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace Bug10938;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * @template TKey
+ * @template TValue
+ * @extends \IteratorAggregate<TKey, TValue>
+ */
+interface Collection extends \IteratorAggregate
+{
+	/**
+	 * @return (TValue is never ? true : bool)
+	 */
+	function isEmpty(): bool;
+}
+
+/** @param Collection<never, never> $c */
+function emptyCollection(Collection $c): void {
+	assertType('true', $c->isEmpty());
+}
+
+/** @param Collection<int, string> $c */
+function nonEmptyCollection(Collection $c): void {
+	assertType('bool', $c->isEmpty());
+}

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

@@ -0,0 +1,29 @@
+<?php declare(strict_types = 1);
+
+namespace Bug9634;
+
+use function PHPStan\Testing\assertType;
+
+/** @template T */
+interface Option {
+	/** @return self<never> */
+	static function none(): self;
+
+	/** @return T */
+	function unwrap(): mixed;
+
+	/**
+	 * @return (T is never ? false : bool)
+	 */
+	function isSome(): bool;
+}
+
+/** @param Option<never> $o */
+function f(Option $o): void {
+	assertType('false', $o->isSome());
+}
+
+/** @param Option<int> $o */
+function g(Option $o): void {
+	assertType('bool', $o->isSome());
+}

tests/PHPStan/Rules/PhpDoc/MethodConditionalReturnTypeRuleTest.php

@@ -102,4 +102,14 @@ public function testBug11939(): void
 		$this->analyse([__DIR__ . '/data/bug-11939.php'], []);
 	}
 
+	public function testBug9634(): void
+	{
+		$this->analyse([__DIR__ . '/../../Analyser/nsrt/bug-9634.php'], []);
+	}
+
+	public function testBug10938(): void
+	{
+		$this->analyse([__DIR__ . '/../../Analyser/nsrt/bug-10938.php'], []);
+	}
+
 }

tests/PHPStan/Type/TemplateTypeTest.php

@@ -281,6 +281,30 @@ public static function dataIsSuperTypeOf(): array
 				TrinaryLogic::createMaybe(),
 				TrinaryLogic::createYes(),
 			],
+			23 => [
+				$templateType('T', null),
+				new NeverType(),
+				TrinaryLogic::createYes(), // T isSuperTypeTo *NEVER* - never is bottom type
+				TrinaryLogic::createMaybe(), // *NEVER* isSuperTypeTo T - T could be never
+			],
+			24 => [
+				$templateType('T', null),
+				new NonAcceptingNeverType(),
+				TrinaryLogic::createYes(), // T isSuperTypeTo never - never is bottom type
+				TrinaryLogic::createMaybe(), // never isSuperTypeTo T - T could be never
+			],
+			25 => [
+				$templateType('T', new ObjectType('DateTime')),
+				new NeverType(),
+				TrinaryLogic::createYes(), // (T of DateTime) isSuperTypeTo *NEVER* - never is bottom type
+				TrinaryLogic::createMaybe(), // *NEVER* isSuperTypeTo (T of DateTime) - T could be never
+			],
+			26 => [
+				$templateType('T', new ObjectType('DateTime')),
+				new NonAcceptingNeverType(),
+				TrinaryLogic::createYes(), // (T of DateTime) isSuperTypeTo never - never is bottom type
+				TrinaryLogic::createMaybe(), // never isSuperTypeTo (T of DateTime) - T could be never
+			],
 		];
 	}