Add support for ListTag type casting and PHPStan generics

Author: dktapps

src/tag/CompoundTag.php

@@ -88,13 +88,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

@@ -34,7 +34,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;
@@ -43,12 +44,13 @@ final class ListTag extends Tag implements \Countable, \IteratorAggregate{
 	private $tagType;
 	/**
 	 * @var \SplDoublyLinkedList|Tag[]
-	 * @phpstan-var \SplDoublyLinkedList<Tag>
+	 * @phpstan-var \SplDoublyLinkedList<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);
@@ -61,7 +63,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{
 		$value = [];
@@ -86,6 +88,34 @@ public function getAllValues() : array{
 		return $result;
 	}
 
+	/**
+	 * @phpstan-template TTarget of Tag
+	 * @phpstan-param class-string<TTarget> $tagClass
+	 * @phpstan-this-out self<TTarget> $this
+	 */
+	private function checkTagClass(string $tagClass) : bool{
+		return $this->value->isEmpty() ?
+			$this->tagType === NBT::TAG_End :
+			$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 and is of TAG_End type, the cast will always succeed, since TAG_End lists
+	 * will have their type updated as soon as a value is inserted. However, casting any other type of
+	 * empty list will fail if the type is incorrect.
+	 *
+	 * @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 $this->value->count();
 	}
@@ -96,6 +126,8 @@ public function getCount() : int{
 
 	/**
 	 * Appends the specified tag to the end of the list.
+	 *
+	 * @phpstan-param TValue $tag
 	 */
 	public function push(Tag $tag) : void{
 		$this->checkTagType($tag);
@@ -104,13 +136,16 @@ public function push(Tag $tag) : void{
 
 	/**
 	 * Removes the last tag from the list and returns it.
+	 * @phpstan-return TValue
 	 */
 	public function pop() : Tag{
 		return $this->value->pop();
 	}
 
 	/**
 	 * Adds the specified tag to the start of the list.
+	 *
+	 * @phpstan-param TValue $tag
 	 */
 	public function unshift(Tag $tag) : void{
 		$this->checkTagType($tag);
@@ -119,6 +154,7 @@ public function unshift(Tag $tag) : void{
 
 	/**
 	 * Removes the first tag from the list and returns it.
+	 * @phpstan-return TValue
 	 */
 	public function shift() : Tag{
 		return $this->value->shift();
@@ -128,6 +164,8 @@ 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-param TValue $tag
+	 *
 	 * @return void
 	 * @throws \OutOfRangeException if the offset is not within the bounds of the list
 	 */
@@ -146,6 +184,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{
@@ -157,13 +197,15 @@ 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{
 		return $this->value->bottom();
 	}
 
 	/**
 	 * Returns the element in the last position in the list (the end), without removing it.
+	 * @phpstan-return TValue
 	 */
 	public function last() : Tag{
 		return $this->value->top();
@@ -172,6 +214,8 @@ public function last() : Tag{
 	/**
 	 * Overwrites the tag at the specified offset.
 	 *
+	 * @phpstan-param TValue $tag
+	 *
 	 * @throws \OutOfRangeException if the offset is not within the bounds of the list
 	 */
 	public function set(int $offset, Tag $tag) : void{
@@ -209,6 +253,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.
 	 *
@@ -263,23 +308,21 @@ public static function read(NbtStreamReader $reader, ReaderTracker $tracker) : s
 	public function write(NbtStreamWriter $writer) : void{
 		$writer->writeByte($this->tagType);
 		$writer->writeInt($this->value->count());
-		/** @var Tag $tag */
 		foreach($this->value as $tag){
 			$tag->write($writer);
 		}
 	}
 
 	protected function stringifyValue(int $indentation) : string{
 		$str = "{\n";
-		/** @var Tag $tag */
 		foreach($this->value as $tag){
 			$str .= str_repeat("  ", $indentation + 1) . $tag->toString($indentation + 1) . "\n";
 		}
 		return $str . str_repeat("  ", $indentation) . "}";
 	}
 
 	public function __clone(){
-		/** @phpstan-var \SplDoublyLinkedList<Tag> $new */
+		/** @phpstan-var \SplDoublyLinkedList<TValue> $new */
 		$new = new \SplDoublyLinkedList();
 
 		foreach($this->value as $tag){
@@ -295,7 +338,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{
 		//we technically don't need iterator_to_array() here, but I don't feel comfortable relying on "yield from" to