Add support for ListTag type casting and PHPStan generics

Author: dktapps

composer.json

@@ -8,7 +8,7 @@
         "pocketmine/binaryutils": "^0.2.0"
     },
     "require-dev": {
-        "phpstan/phpstan": "2.1.0",
+        "phpstan/phpstan": "2.1.27",
         "phpunit/phpunit": "^9.5",
         "phpstan/extension-installer": "^1.0",
         "phpstan/phpstan-strict-rules": "^2.0",

src/tag/CompoundTag.php

@@ -91,13 +91,26 @@ public function getTag(string $name) : ?Tag{
 	/**
 	 * Returns the ListTag with the specified name, or null if it does not exist. Triggers an exception if a tag exists
 	 * with that name and the tag is not a ListTag.
+	 *
+	 * @phpstan-template TValue of Tag
+	 * @phpstan-param class-string<TValue> $tagClass
+	 * @phpstan-return ListTag<TValue>|null
+	 *
+	 * @throws UnexpectedTagTypeException
 	 */
-	public function getListTag(string $name) : ?ListTag{
+	public function getListTag(string $name, string $tagClass = Tag::class) : ?ListTag{
 		$tag = $this->getTag($name);
-		if($tag !== null && !($tag instanceof ListTag)){
-			throw new UnexpectedTagTypeException("Expected a tag of type " . ListTag::class . ", got " . get_class($tag));
+		if($tag !== null){
+			if(!$tag instanceof ListTag){
+				throw new UnexpectedTagTypeException("Expected a tag of type " . ListTag::class . ", got " . get_class($tag));
+			}
+			$casted = $tag->cast($tagClass);
+			if($casted === null){
+				throw new UnexpectedTagTypeException("Unable to cast list to ListTag<$tagClass>");
+			}
+			return $casted;
 		}
-		return $tag;
+		return null;
 	}
 
 	/**

src/tag/ListTag.php

@@ -42,7 +42,8 @@
 use function str_repeat;
 
 /**
- * @phpstan-implements \IteratorAggregate<int, Tag>
+ * @phpstan-template TValue of Tag = Tag
+ * @phpstan-implements \IteratorAggregate<int, TValue>
  */
 final class ListTag extends Tag implements \Countable, \IteratorAggregate{
 	use NoDynamicFieldsTrait;
@@ -51,12 +52,13 @@ final class ListTag extends Tag implements \Countable, \IteratorAggregate{
 	private $tagType;
 	/**
 	 * @var Tag[]
-	 * @phpstan-var list<Tag>
+	 * @phpstan-var list<TValue>
 	 */
 	private $value = [];
 
 	/**
 	 * @param Tag[] $value
+	 * @phpstan-param TValue[] $value
 	 */
 	public function __construct(array $value = [], int $tagType = NBT::TAG_End){
 		self::restrictArgCount(__METHOD__, func_num_args(), 2);
@@ -68,7 +70,7 @@ public function __construct(array $value = [], int $tagType = NBT::TAG_End){
 
 	/**
 	 * @return Tag[]
-	 * @phpstan-return list<Tag>
+	 * @phpstan-return list<TValue>
 	 */
 	public function getValue() : array{
 		return $this->value;
@@ -83,6 +85,31 @@ public function getAllValues() : array{
 		return array_map(fn(Tag $t) => $t->getValue(), $this->value);
 	}
 
+	/**
+	 * @phpstan-template TTarget of Tag
+	 * @phpstan-param class-string<TTarget> $tagClass
+	 * @phpstan-this-out self<TTarget> $this
+	 */
+	private function checkTagClass(string $tagClass) : bool{
+		return count($this->value) === 0 || $this->first() instanceof $tagClass;
+	}
+
+	/**
+	 * Returns $this if the tag values are of type $tagClass, null otherwise.
+	 * The returned value will have the proper PHPStan generic types set if it matches.
+	 *
+	 * If the list is empty, the cast will always succeed, as empty lists infer their
+	 * type from the first value inserted.
+	 *
+	 * @phpstan-template TTarget of Tag
+	 * @phpstan-param class-string<TTarget> $tagClass
+	 *
+	 * @phpstan-return self<TTarget>|null
+	 */
+	public function cast(string $tagClass) : ?self{
+		return $this->checkTagClass($tagClass) ? $this : null;
+	}
+
 	public function count() : int{
 		return count($this->value);
 	}
@@ -93,6 +120,10 @@ public function getCount() : int{
 
 	/**
 	 * Appends the specified tag to the end of the list.
+	 *
+	 * @phpstan-template TNewValue of TValue
+	 * @phpstan-param TNewValue $tag
+	 * @phpstan-this-out self<TNewValue>
 	 */
 	public function push(Tag $tag) : void{
 		$this->checkTagType($tag);
@@ -101,6 +132,7 @@ public function push(Tag $tag) : void{
 
 	/**
 	 * Removes the last tag from the list and returns it.
+	 * @phpstan-return TValue
 	 */
 	public function pop() : Tag{
 		if(count($this->value) === 0){
@@ -111,6 +143,10 @@ public function pop() : Tag{
 
 	/**
 	 * Adds the specified tag to the start of the list.
+	 *
+	 * @phpstan-template TNewValue of TValue
+	 * @phpstan-param TNewValue $tag
+	 * @phpstan-this-out self<TNewValue>
 	 */
 	public function unshift(Tag $tag) : void{
 		$this->checkTagType($tag);
@@ -119,6 +155,7 @@ public function unshift(Tag $tag) : void{
 
 	/**
 	 * Removes the first tag from the list and returns it.
+	 * @phpstan-return TValue
 	 */
 	public function shift() : Tag{
 		if(count($this->value) === 0){
@@ -131,6 +168,10 @@ public function shift() : Tag{
 	 * Inserts a tag into the list between existing tags, at the specified offset. Later values in the list are moved up
 	 * by 1 position.
 	 *
+	 * @phpstan-template TNewValue of TValue
+	 * @phpstan-param TNewValue $tag
+	 * @phpstan-this-out self<TNewValue>
+	 *
 	 * @return void
 	 * @throws \OutOfRangeException if the offset is not within the bounds of the list
 	 */
@@ -158,6 +199,8 @@ public function remove(int $offset) : void{
 	/**
 	 * Returns the tag at the specified offset.
 	 *
+	 * @phpstan-return TValue
+	 *
 	 * @throws \OutOfRangeException if the offset is not within the bounds of the list
 	 */
 	public function get(int $offset) : Tag{
@@ -169,6 +212,7 @@ public function get(int $offset) : Tag{
 
 	/**
 	 * Returns the element in the first position of the list, without removing it.
+	 * @phpstan-return TValue
 	 */
 	public function first() : Tag{
 		if(count($this->value) === 0){
@@ -179,6 +223,7 @@ public function first() : Tag{
 
 	/**
 	 * Returns the element in the last position in the list (the end), without removing it.
+	 * @phpstan-return TValue
 	 */
 	public function last() : Tag{
 		if(count($this->value) === 0){
@@ -190,6 +235,10 @@ public function last() : Tag{
 	/**
 	 * Overwrites the tag at the specified offset.
 	 *
+	 * @phpstan-template TNewValue of TValue
+	 * @phpstan-param TNewValue $tag
+	 * @phpstan-this-out self<TNewValue>
+	 *
 	 * @throws \OutOfRangeException if the offset is not within the bounds of the list
 	 */
 	public function set(int $offset, Tag $tag) : void{
@@ -230,6 +279,7 @@ public function getTagType() : int{
 	}
 
 	/**
+	 * @deprecated
 	 * Sets the type of tag that can be added to this list. If TAG_End is used, the type will be auto-detected from the
 	 * first tag added to the list.
 	 *
@@ -307,7 +357,7 @@ protected function makeCopy(){
 
 	/**
 	 * @return \Generator|Tag[]
-	 * @phpstan-return \Generator<int, Tag, void, void>
+	 * @phpstan-return \Generator<int, TValue, void, void>
 	 */
 	public function getIterator() : \Generator{
 		yield from $this->value;

src/tag/Tag.php

@@ -57,6 +57,7 @@ abstract protected function stringifyValue(int $indentation) : string;
 	 * Used for cloning tags in tags that have children.
 	 *
 	 * @throws \RuntimeException if a recursive dependency was detected
+	 * @return static
 	 */
 	public function safeClone() : Tag{
 		if($this->cloning){

tests/phpstan/configs/phpstan-bugs.neon

@@ -13,13 +13,37 @@ parameters:
 			path: ../../../src/tag/IntArrayTag.php
 
 		-
-			message: '#^Property pocketmine\\nbt\\tag\\ListTag\:\:\$value \(list\<pocketmine\\nbt\\tag\\Tag\>\) does not accept non\-empty\-array\<int\<0, max\>, pocketmine\\nbt\\tag\\Tag\>\.$#'
+			message: '#^Property pocketmine\\nbt\\tag\\ListTag\<TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\:\:\$value \(list\<TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\) does not accept non\-empty\-array\<int\<0, max\>, \(TNewValue of TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\)\|TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\.$#'
 			identifier: assign.propertyType
 			count: 1
 			path: ../../../src/tag/ListTag.php
 
+		-
+			message: '#^Property pocketmine\\nbt\\tag\\ListTag\<TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\:\:\$value \(list\<TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\) does not accept non\-empty\-list\<\(TNewValue of TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\)\|TValue of pocketmine\\nbt\\tag\\Tag \= pocketmine\\nbt\\tag\\Tag\>\.$#'
+			identifier: assign.propertyType
+			count: 3
+			path: ../../../src/tag/ListTag.php
+
 		-
 			message: '#^Call to function is_string\(\) with string will always evaluate to true\.$#'
 			identifier: function.alreadyNarrowedType
 			count: 1
 			path: ../../phpunit/tag/CompoundTagTest.php
+
+		-
+			message: '#^Call to static method PHPUnit\\Framework\\Assert\:\:assertNotSame\(\) with \*NEVER\* and pocketmine\\nbt\\tag\\Tag will always evaluate to true\.$#'
+			identifier: staticMethod.alreadyNarrowedType
+			count: 1
+			path: ../../phpunit/tag/ListTagTest.php
+
+		-
+			message: '#^Call to static method PHPUnit\\Framework\\Assert\:\:assertSame\(\) with \*NEVER\* and pocketmine\\nbt\\tag\\Tag will always evaluate to false\.$#'
+			identifier: staticMethod.impossibleType
+			count: 1
+			path: ../../phpunit/tag/ListTagTest.php
+
+		-
+			message: '#^Instanceof between \*NEVER\* and pocketmine\\nbt\\tag\\ImmutableTag will always evaluate to false\.$#'
+			identifier: instanceof.alwaysFalse
+			count: 1
+			path: ../../phpunit/tag/ListTagTest.php

tests/phpunit/tag/CompoundTagTest.php

@@ -24,6 +24,7 @@
 namespace pocketmine\nbt\tag;
 
 use PHPUnit\Framework\TestCase;
+use pocketmine\nbt\UnexpectedTagTypeException;
 use pocketmine\utils\Limits;
 use function array_fill;
 use function str_repeat;
@@ -195,5 +196,27 @@ public function testNameLength() : void{
 		$tag->setTag(str_repeat(".", Limits::INT16_MAX + 1), new IntTag(1)); //error
 	}
 
+	public function testGetListTagWithType() : void{
+		$tag = CompoundTag::create()
+			->setTag("empty", new ListTag())
+			->setTag("string1", new ListTag([new StringTag("string1")]));
+
+		//empty always works
+		self::assertNotNull($tag->getListTag("empty", CompoundTag::class));
+		self::assertNotNull($tag->getListTag("empty", StringTag::class));
+		self::assertNotNull($tag->getListTag("string1", StringTag::class));
+
+		self::assertNotNull($tag->getListTag("empty")); //no type also allowed
+		self::assertNotNull($tag->getListTag("string1"));
+	}
+
+	public function testGetListTagWithTypeErrors() : void{
+		$tag = CompoundTag::create()
+			->setTag("string1", new ListTag([new StringTag("string1")]));
+
+		$this->expectException(UnexpectedTagTypeException::class);
+		$tag->getListTag("string1", IntTag::class);
+	}
+
 	//TODO: add more tests
 }

tests/phpunit/tag/ListTagTest.php

@@ -178,4 +178,21 @@ public function testEquals() : void{
 		self::assertFalse($list1->equals($differentValue));
 		self::assertFalse($differentValue->equals($list1));
 	}
+
+	public static function castProvider() : \Generator{
+		yield [new ListTag(), StringTag::class, true]; //empty list can be casted to any type
+		yield [new ListTag([new StringTag("hello")]), StringTag::class, true];
+		yield [new ListTag([new StringTag("hello"), new StringTag("hello2")]), StringTag::class, true];
+		yield [new ListTag([new StringTag("hello")]), IntTag::class, false];
+		yield [new ListTag([new StringTag("hello"), new StringTag("hello2")]), IntTag::class, false];
+	}
+
+	/**
+	 * @phpstan-template TClass of Tag
+	 * @phpstan-param class-string<TClass> $targetClass
+	 * @dataProvider castProvider
+	 */
+	public function testCast(ListTag $in, string $targetClass, bool $succeeds) : void{
+		self::assertSame($succeeds, $in->cast($targetClass) !== null);
+	}
 }