PHPackages                             cartograph/minecraft-nbt - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. cartograph/minecraft-nbt

ActiveLibrary[Parsing & Serialization](/categories/parsing)

cartograph/minecraft-nbt
========================

Read, write, and manipulate Minecraft's NBT (Named Binary Tag) format; both binary and SNBT.

v1.0.0(1mo ago)074—5%1MITPHPPHP ^8.5CI passing

Since May 7Pushed 1mo agoCompare

[ Source](https://github.com/cartographgg/minecraft-nbt)[ Packagist](https://packagist.org/packages/cartograph/minecraft-nbt)[ Docs](https://github.com/cartographgg/minecraft-nbt)[ RSS](/packages/cartograph-minecraft-nbt/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (1)

 [![Cartograph Logo](cartograph-logo.png)](cartograph-logo.png)

Minecraft NBT
=============

[](#minecraft-nbt)

A pure-PHP library for reading, writing, and manipulating Minecraft's NBT (Named Binary Tag) format, in both binary (file and network) form and SNBT.

[![Packagist Version](https://camo.githubusercontent.com/c4340e20579f282ec40aa8d26494306fe5ae2b1c72239d61c6e34f403386ad66/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636172746f67726170682f6d696e6563726166742d6e62742e737667)](https://packagist.org/packages/cartograph/minecraft-nbt)[![Total Downloads](https://camo.githubusercontent.com/d4eaccdd1971ec282a3e28db196de72d76634d25661a070a550b30af9a2e8978/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636172746f67726170682f6d696e6563726166742d6e62742e737667)](https://packagist.org/packages/cartograph/minecraft-nbt)[![PHP Version](https://camo.githubusercontent.com/e6b25ef0b6404c97b4f250ff668a8abe6118d5c05bb781bab2e59e03d0df2477/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f636172746f67726170682f6d696e6563726166742d6e62742e737667)](https://packagist.org/packages/cartograph/minecraft-nbt)[![License](https://camo.githubusercontent.com/190fdeef3fb55e4a9f68d2fd144ff3247c139e7b2ab62c3f7c26df2207bb1074/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f636172746f67726170682f6d696e6563726166742d6e62742e737667)](LICENSE.md)

Features
--------

[](#features)

- **Binary NBT**: read and write the file format (named root) and the network format (unnamed root, Minecraft 1.20.2+)
- **Compression**: auto-detects GZip and Zlib on read; choose any of GZip, Zlib, or none on write
- **SNBT**: parse and render stringified NBT, with optional pretty-printing and configurable quote style
- **1.21.5 SNBT extensions**: typed-array prefixes (`[B;...]`, `[I;...]`, `[L;...]`), signed/unsigned suffixes (`42ub`, `100sl`, ...), hex (`0xFF`) and binary (`0b1010`) literals, underscore digit separators, trailing commas
- **All 13 tag types**: Byte, Short, Int, Long, Float, Double, ByteArray, String, List, Compound, IntArray, LongArray, plus End for empty lists
- **Type-safe construction**: element-type validation on List and array tags, range-checked numeric tags
- **PHPStan level max**: full generic annotations on `Tag`, `CompoundTag`, `ListTag`, and the `Nbt` facade

Requirements
------------

[](#requirements)

- PHP 8.5 or newer
- ext-zlib (compiled in by default on most distributions)

Installation
------------

[](#installation)

Install via Composer:

```
composer require cartograph/minecraft-nbt
```

Quick start
-----------

[](#quick-start)

Build a tag tree and write it to a file:

```
use Cartograph\NBT\Nbt;

$tag = Nbt::compound([
    'name'  => Nbt::string('Bananrama'),
    'level' => Nbt::int(42),
]);

Nbt::writeFile($tag, 'player.nbt');
```

That's a complete, runnable example, with no fixtures and no setup. The output is a GZip-compressed binary NBT file with a TAG\_Compound root containing one string and one int child.

To read it back:

```
$tag = Nbt::readFile('player.nbt');

echo $tag->get('name')->value();      // "Bananrama"
echo $tag->get('level')->value();     // 42
```

Concepts
--------

[](#concepts)

NBT is a tree of typed tags. Every tree has a `CompoundTag` at its root, which is an ordered map of named children. Children can be other compounds (nesting), `ListTag`s (homogeneous, ordered sequences of tags), or any of the leaf types: `Byte`, `Short`, `Int`, `Long`, `Float`, `Double`, `String`, `ByteArray`, `IntArray`, or `LongArray`.

The same tree can be serialised two ways:

- **Binary NBT**, the compact wire format used by Minecraft itself, with optional GZip or Zlib compression
- **SNBT**, a human-readable text representation, similar to JSON with type suffixes (`42b`, `1.5f`, `[L;1L,2L,3L]`)

This library reads, writes, parses, and renders both.

Usage
-----

[](#usage)

### Read a binary file

[](#read-a-binary-file)

`readFile` auto-detects GZip and Zlib compression from the file's leading bytes; uncompressed files work too.

```
use Cartograph\NBT\Nbt;

$level = Nbt::readFile('level.dat');

echo $level->get('Data')->get('LevelName')->value();
```

### Write a binary file

[](#write-a-binary-file)

GZip is the default. Pass a different `Compression` to override.

```
use Cartograph\NBT\Binary\Compression;
use Cartograph\NBT\Nbt;

Nbt::writeFile($tag, 'data.nbt');                                    // GZip
Nbt::writeFile($tag, 'data.zlib.nbt', '', Compression::Zlib);
Nbt::writeFile($tag, 'data.raw.nbt', '', Compression::None);
```

The third argument is the root tag's name (most files use an empty string).

### Parse SNBT

[](#parse-snbt)

`parseSnbt` accepts the full SNBT grammar including 1.21.5 extensions: typed-array prefixes, signed/unsigned suffixes, hex/binary literals, underscore digit separators, and trailing commas.

```
use Cartograph\NBT\Nbt;

$tag = Nbt::parseSnbt('{name: "Bananrama", level: 42b, scores: [1, 2, 3]}');

echo $tag->get('name')->value();           // "Bananrama"
echo $tag->get('level')->value();          //  42 (ByteTag)
echo $tag->get('scores')->get(1)->value(); //  2  (IntTag)
```

### Render SNBT

[](#render-snbt)

Two modes via `SnbtOptions`: compact (default) and pretty.

```
use Cartograph\NBT\Nbt;
use Cartograph\NBT\Snbt\SnbtOptions;

echo Nbt::renderSnbt($tag);
// {name:Bananrama,level:42b,scores:[1,2,3,],}

echo Nbt::renderSnbt($tag, new SnbtOptions(prettyPrint: true));
// {
//     name:Bananrama,
//     level:42b,
//     scores:[
//         1,
//         2,
//         3,
//     ],
// }
```

`SnbtOptions` also lets you force-quote keys (`quoteKeys: true`), pick a preferred quote style (`quoteStyle: QuoteStyle::Single`), and choose the indentation unit.

### Network format (Minecraft 1.20.2+)

[](#network-format-minecraft-1202)

The network protocol uses an unnamed root compound. `Nbt::readNetworkBinary`and `Nbt::writeNetworkBinary` handle it.

```
use Cartograph\NBT\Nbt;

$bytes = Nbt::writeNetworkBinary($tag);
$tag   = Nbt::readNetworkBinary($bytes);
```

Class overview
--------------

[](#class-overview)

All tag classes live in the `Cartograph\NBT\Tags` namespace.

ClassHoldsNotes`ByteTag``int`-128 to 127`ShortTag``int`-32 768 to 32 767`IntTag``int`signed 32-bit`LongTag``int`signed 64-bit (full PHP `int` range)`FloatTag``float`IEEE 754 single-precision`DoubleTag``float`IEEE 754 double-precision`StringTag``string`UTF-8, max 65 535 bytes`ByteArrayTag``int[]`each element in `ByteTag` range`IntArrayTag``int[]`each element in `IntTag` range`LongArrayTag``int[]`(PHP `int` always fits)`CompoundTag``array`ordered map of named children`ListTag``list`homogeneous; element type declared at constructionThe `Nbt` facade has a factory method for each (`Nbt::byte()`, `Nbt::compound()`, ...) that returns the corresponding tag instance.

Compatibility
-------------

[](#compatibility)

This library targets the **Java Edition** NBT format. All 13 tag types (including TAG\_End for empty lists) are supported.

- **File format**: fully supported, all Minecraft Java versions
- **Network format**: Minecraft Java 1.20.2 and newer (unnamed root compound)
- **Compression**: GZip, Zlib, and uncompressed
- **SNBT**: classic syntax plus the 1.21.5 grammar extensions

Bedrock Edition's NBT variant (little-endian, varint-prefixed) is not supported.

Contributing
------------

[](#contributing)

Bug reports, feature requests, and pull requests are welcome at [github.com/cartographgg/minecraft-nbt](https://github.com/cartographgg/minecraft-nbt). See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup and the required checks (tests, static analysis, code style, and mutation testing). Each check has a Composer script: `composer test`, `composer static`, `composer style`, and `composer mutation`.

License
-------

[](#license)

Released under the [MIT License](LICENSE.md). © Cartograph contributors.

---

Maintained as part of [Cartograph](https://cartograph.gg), a Minecraft server directory and monitoring platform. The library is self-contained and has no Cartograph-specific behaviour; use it anywhere you need to work with NBT data in PHP.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance93

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

33d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/469515?v=4)[Ollie Read](/maintainers/ollieread)[@ollieread](https://github.com/ollieread)

---

Top Contributors

[![ollieread](https://avatars.githubusercontent.com/u/469515?v=4)](https://github.com/ollieread "ollieread (2 commits)")

---

Tags

codecminecraftminecraft-javaminecraft-nbtnamed-binary-tagnbtparserphpsnbtparserNBTminecraftcodecsnbtnamed binary tag

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/cartograph-minecraft-nbt/health.svg)

```
[![Health](https://phpackages.com/badges/cartograph-minecraft-nbt/health.svg)](https://phpackages.com/packages/cartograph-minecraft-nbt)
```

###  Alternatives

[nikic/php-parser

A PHP parser written in PHP

17.4k936.5M2.3k](/packages/nikic-php-parser)[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k942.7M149](/packages/doctrine-lexer)[erusev/parsedown

Parser for Markdown.

15.0k155.2M835](/packages/erusev-parsedown)[league/commonmark

Highly-extensible PHP Markdown parser which fully supports the CommonMark spec and GitHub-Flavored Markdown (GFM)

3.0k426.1M927](/packages/league-commonmark)[masterminds/html5

An HTML5 parser and serializer.

1.8k260.4M292](/packages/masterminds-html5)[sabberworm/php-css-parser

Parser for CSS Files written in PHP

1.8k204.2M72](/packages/sabberworm-php-css-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)