Merge branch 'stable' into ext-encoding

Author: dktapps

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
       id: composer-cache
       uses: actions/cache@v4
       with:
-        path: "~/.composer/cache"
+        path: "~/.cache/composer"
         key: "php-${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}"
         restore-keys: "php-${{ matrix.php }}-composer-"
 

README.md

@@ -2,3 +2,102 @@
 ![CI](https://github.com/pmmp/NBT/workflows/CI/badge.svg)
 
 PHP library for working with the NBT (Named Binary Tag) data storage format, as designed by Mojang.
+
+## Examples
+
+The library provides two NBT serializers: `BigEndianNbtSerializer` (typically suited for Minecraft Java) and `LittleEndianNbtSerializer` (typically used by Bedrock for storage).
+
+Note: Bedrock network NBT (which uses varints in some places) is not implemented here. See [BedrockProtocol](https://github.com/pmmp/BedrockProtocol) for that.
+
+Note: `TAG_LongArray` is not supported because Bedrock doesn't support it, so it's not clear how NBT trees intended for serialization by Bedrock would be restricted from using it.
+
+### Reading data
+```php
+use pocketmine\nbt\LittleEndianNbtSerializer;
+use pocketmine\nbt\NbtDataException;
+use pocketmine\nbt\NoSuchTagException;
+use pocketmine\nbt\UnexpectedTagTypeException;
+use pocketmine\nbt\tag\StringTag;
+
+$serializer = new LittleEndianNbtSerializer();
+$optionalStartOffset = 0;
+$optionalMaxDepth = 0; //unlimited by default
+$treeRoot = $serializer->read($yourInputBytes, $optionalStartOffset, $optionalMaxDepth);
+
+try{
+    //If you expect a TAG_Compound root (the most common case)
+    $data = $treeRoot->mustGetCompoundTag());
+}catch(NbtDataException $e){
+    var_dump("root isn't a TAG_Compound");
+}
+//For other, less common cases where the root tag isn't a compound
+var_dump($treeRoot->getTag());
+
+var_dump($treeRoot->getName()); //typically empty
+
+try{
+    var_dump($data->getString("hello"));
+}catch(UnexpectedTagTypeException $e){
+    var_dump("not a TAG_String");
+}catch(NoSuchTagException $e){
+    var_dump("no such tag called \"hello\"");
+}
+
+try{
+    $nestedCompound = $data->getCompoundTag("nestedCompound");
+}catch(UnexpectedTagTypeException $e){
+    var_dump("not a TAG_Compound");
+}
+if($nestedCompound === null){
+    //For legacy BC reasons, this works differently than the primitive type getters like getString() getInt() etc
+    var_dump("no such nested tag called \"nestedCompound\"");
+}
+
+try{
+    $nestedList = $data->getListTag("listOfStrings", StringTag::class);
+}catch(UnexpectedTagTypeException $e){
+    var_dump("not a list of strings");
+}
+if($nestedList === null){
+    //For legacy BC reasons, getListTag() returns NULL if the tag doesn't exist
+    var_dump("no such nested tag called \"listOfStrings\"");
+}
+var_dump($nestedList->getValue()); //StringTag[]
+```
+
+### Writing data
+
+```php
+use pocketmine\nbt\LittleEndianNbtSerializer;
+use pocketmine\nbt\TreeRoot;
+use pocketmine\nbt\tag\CompoundTag;
+use pocketmine\nbt\tag\IntTag;
+use pocketmine\nbt\tag\ListTag;
+use pocketmine\nbt\tag\StringTag;
+
+$compound = CompoundTag::create()
+    ->setByte("byte", 1)
+    ->setInt("int", 2)
+    ->setTag("list", new ListTag([
+        new StringTag("item1"),
+        new StringTag("item2")
+    ]))
+    ->setTag("compound", CompoundTag::create()
+        ->setByte("nestedByte", 1)
+    );
+
+//empty lists infer their type from the first value added
+$list = new ListTag();
+$list->push(new StringTag("hello")); //list is now ListTag<StringTag>
+try{
+    $list->push(new IntTag(1));
+}catch(\TypeError $e){
+    var_dump("can't push an int into a string list");
+}
+
+$serializer = new LittleEndianNbtSerializer();
+$bytes = $serializer->write($treeRoot);
+
+//or if you have a Tag instance
+$bytes = $serializer->write(new TreeRoot($data, "optionalRootName"));
+```

composer.json

@@ -8,10 +8,11 @@
         "ext-encoding": "~1.0.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"
+        "phpstan/phpstan-strict-rules": "^2.0",
+        "phpstan/phpstan-phpunit": "^2.0"
     },
     "license": "LGPL-3.0",
     "autoload": {

phpstan.neon.dist

@@ -1,4 +1,5 @@
 includes:
+	- tests/phpstan/configs/expected-test-errors.neon
 	- tests/phpstan/configs/impossible-mixed.neon
 	- tests/phpstan/configs/phpstan-bugs.neon
 
@@ -7,3 +8,4 @@ parameters:
 	treatPhpDocTypesAsCertain: false
 	paths:
 		- src
+		- tests

src/tag/CompoundTag.php

@@ -90,13 +90,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/expected-test-errors.neon

@@ -0,0 +1,13 @@
+parameters:
+	ignoreErrors:
+		-
+			message: '#^Expression "clone \$tag" on a separate line does not do anything\.$#'
+			identifier: expr.resultUnused
+			count: 1
+			path: ../../phpunit/tag/CompoundTagTest.php
+
+		-
+			message: '#^Expression "clone \$tag" on a separate line does not do anything\.$#'
+			identifier: expr.resultUnused
+			count: 1
+			path: ../../phpunit/tag/ListTagTest.php

tests/phpstan/configs/phpstan-bugs.neon

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