v1.0.0

This release replaces the JSON round-trip with a direct parser. parse() keeps its return values. A new parseTyped() returns a tag tree that keeps the NBT types and can serialize back to SNBT.

What's Changed

• Direct SNBT parser with a typed tag tree by @m-stilling in #1

Added

• SNBTParser::parseTyped(string $input): Tag parses SNBT into a typed tag tree. Every value is a Tag subclass under Stilling\SNBTParser\Tag: ByteTag, ShortTag, IntTag, LongTag, FloatTag, DoubleTag, BooleanTag, StringTag, ByteArrayTag, IntArrayTag, LongArrayTag, ListTag and CompoundTag. The tree tells 0b, 0s, 0 and 0L apart.
• Tag::toPhp() returns the native PHP value. This is the same value that parse() returns.
• Tag::toSnbt(SNBTFormat $format = SNBTFormat::Compact) serializes the tag back to SNBT and keeps the NBT types. A compact data get blob round-trips byte for byte.
• SNBTFormat selects the layout of toSnbt(). Compact gives {a:1,b:[1,2]}. Spaced gives { a: 1, b: [ 1, 2 ] }. Pretty puts compounds and lists on multiple lines with four-space indentation, and keeps typed number arrays on one line.
• CompoundTag::get(string $key): ?Tag and CompoundTag::has(string $key): bool read compound entries. ListTag::get(int $index): ?Tag reads list items.
• CompoundTag, ListTag and the three number array tags implement Countable and IteratorAggregate. count($tag) and foreach ($tag as $key => $value) work on them. The readonly entries, items and values properties expose the contents as arrays.
• examples/parse-typed.php dumps a typed tree, its toPhp() value and its toSnbt() output.

Changed

• parse() now delegates to parseTyped()->toPhp(). The return values do not change: every integer type becomes int, every floating-point type becomes float, true and false become bool.
• Unquoted string values parse. { id: stone } returns [ "id" => "stone" ]. Earlier versions threw on this input.
• The escape sequences \n, \r and \t decode to the control characters. toSnbt() writes them back as escape sequences.
• [B; true, false] parses to the bytes 1 and 0. Earlier versions returned 0 for both.
• Invalid typed-array elements throw SNBTParseException. This covers [I; foo], [I; 1.5], [I; 1f] and boolean keywords outside a byte array. Earlier versions returned 0 for these elements. Any integer suffix is still accepted in any array type, so [I; 1b, 2s] parses.
• Parse errors report the byte position and the text near it. Example: Expected ',' or '}' at position 6 near "x: 1}".

Removed

• The ext-mbstring requirement. The package needs no PHP extensions.
• The internal Stilling\SNBTParser\Tokens namespace. It was not part of the public API.

Compatibility

• PHP 8.3, 8.4 and 8.5 are supported. The CI matrix tests all three with the lowest and the highest dependency versions.
• SNBTParser::parse() and SNBTParser::intsToUuid() keep their signatures. The declared return type of parse() no longer lists object, which it never returned.

Upgrading from 0.3

No code changes are needed for parse() and intsToUuid(). Check these points:

• If your input relied on invalid typed-array elements parsing as 0, it now throws. Fix the input, or catch SNBTParseException.
• If your input contained \n, \r or \t escape sequences, the values now contain the control characters instead of the two-character sequences.
• If you catch parse errors by message text, update the patterns. The messages changed.

Full Changelog: v0.3.0...v1.0.0