PHPackages                             aternos/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. aternos/nbt

ActiveLibrary

aternos/nbt
===========

PHP library to parse, modify, and create NBT objects

v1.12.1(1y ago)17118.6k↑42.9%44MITPHPPHP >=8.1

Since Sep 2Pushed 1y ago2 watchersCompare

[ Source](https://github.com/aternosorg/php-nbt)[ Packagist](https://packagist.org/packages/aternos/nbt)[ RSS](/packages/aternos-nbt/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (29)Used By (4)

php-nbt
=======

[](#php-nbt)

A full PHP implementation of Minecraft's Named Binary Tag (NBT) format.

In contrast to other implementations, this library provides full support for 64-bit types, including the relatively new `TAG_Long_Array`.

Additionally, all three flavors (Java Edition, Bedrock Edition/little endian, and Bedrock Edition/VarInt) of the NBT format are supported.

### Installation

[](#installation)

```
composer require aternos/nbt
```

Usage
-----

[](#usage)

### Reading NBT data

[](#reading-nbt-data)

To read existing NBT data, a Reader object is required. This library implements different readers to read NBT data from strings.

```
//Read uncompressed NBT data
$reader = new \Aternos\Nbt\IO\Reader\StringReader("...nbtData...", \Aternos\Nbt\NbtFormat::BEDROCK_EDITION);

//Read gzip compressed NBT data
$gzipReader = new \Aternos\Nbt\IO\Reader\GZipCompressedStringReader("...compressedNbtData...", \Aternos\Nbt\NbtFormat::JAVA_EDITION);

//Read zlib compressed NBT data
$zlibReader = new \Aternos\Nbt\IO\Reader\ZLibCompressedStringReader("...compressedNbtData...", \Aternos\Nbt\NbtFormat::BEDROCK_EDITION_NETWORK);
```

Note that the reader object is also used to specify the NBT format flavor. Available are `\Aternos\Nbt\NbtFormat::JAVA_EDITION`, `\Aternos\Nbt\NbtFormat::BEDROCK_EDITION`, and `\Aternos\Nbt\NbtFormat::BEDROCK_EDITION_NETWORK`.

More advanced readers can be created by implementing the `\Aternos\Nbt\IO\Reader\Reader` interface or by extending the `\Aternos\Nbt\IO\Reader\AbstractReader` class.

A reader object can be used to load the NBT tag.

```
$reader = new \Aternos\Nbt\IO\Reader\StringReader("...nbtData...", \Aternos\Nbt\NbtFormat::BEDROCK_EDITION);

$tag = \Aternos\Nbt\Tag\Tag::load($reader);
```

In theory, any type of NBT tag could be returned, but in reality all NBT files will start with either a compound tag or a list tag.

### Manipulating NBT structures

[](#manipulating-nbt-structures)

Tag values of type `TAG_Byte`, `TAG_Short`, `TAG_Int`, `TAG_Long`, `TAG_Float`, `TAG_Double`, `TAG_String` can be accessed via their `getValue()` and `setValue()` functions.

```
$myInt new \Aternos\Nbt\Tag\IntTag();

$myInt->setValue(42);
echo $myInt->getValue(); // 42
```

On String tags, `getValue()` and `setValue()` use the UTF-8 encoding and convert strings based on the selected NBT flavor when being serialized.

Compound tags, list tags, and array tags implement the `ArrayAccess`, `Countable`, and `Iterator` interfaces and can therefore be accessed as arrays.

```
$myCompound = new \Aternos\Nbt\Tag\CompoundTag();

$myCompound["myInt"] = (new \Aternos\Nbt\Tag\IntTag())->setValue(42);
$myCompound["myFloat"] = (new \Aternos\Nbt\Tag\IntTag())->setValue(42.42);
echo count($myCompound); // 2

//Manually setting a list's type is not strictly necessary,
//since it's type will be set automatically when the first element is added
$myList = (new \Aternos\Nbt\Tag\ListTag())->setContentTag(\Aternos\Nbt\Tag\TagType::TAG_String);

$myList[] = (new \Aternos\Nbt\Tag\StringTag())->setValue("Hello");
$myList[] = (new \Aternos\Nbt\Tag\StringTag())->setValue("World");
```

Alternatively, compound tags can be accessed using getter/setter functions. This is especially useful in combination with the new PHP null safe operator.

```
/** @var \Aternos\Nbt\Tag\CompoundTag $playerDat */
$playerDat = \Aternos\Nbt\Tag\Tag::load($reader);

$playerDat->set("foo", (new \Aternos\Nbt\Tag\StringTag())->setValue("bar")); //Set a value
$playerDat->delete("foo"); //Delete a value

$playerName = $playerDat->getCompound("bukkit")?->getString("lastKnownName")?->getValue();
echo $playerName ?? "Unknown player name";
```

### Serializing NBT structures

[](#serializing-nbt-structures)

Similar to the reader object to read NBT data, a writer object is required to write NBT data.

```
//Write uncompressed NBT data
$writer = (new \Aternos\Nbt\IO\Writer\StringWriter())->setFormat(\Aternos\Nbt\NbtFormat::BEDROCK_EDITION);

//Write gzip compressed NBT data
$gzipWriter = (new \Aternos\Nbt\IO\Writer\GZipCompressedStringWriter())->setFormat(\Aternos\Nbt\NbtFormat::JAVA_EDITION);

//Write zlib compressed NBT data
$gzipWriter = (new \Aternos\Nbt\IO\Writer\ZLibCompressedStringWriter())->setFormat(\Aternos\Nbt\NbtFormat::BEDROCK_EDITION_NETWORK);
```

The NBT flavor used by a writer object can differ from the one used by the reader object that was originally used to read the NBT structure. It is therefore possible to use this library to convert NBT structures between the different formats.

More advanced writers can be created by implementing the `\Aternos\Nbt\IO\Writer\Writer` interface or by extending the `\Aternos\Nbt\IO\Writer\AbstractWriter` class.

A writer object can be used to write/serialize an NBT structure.

```
$writer = (new \Aternos\Nbt\IO\Writer\StringWriter())->setFormat(\Aternos\Nbt\NbtFormat::BEDROCK_EDITION);

$tag->write($writer);
file_put_contents("data.nbt", $writer->getStringData());
```

### Bedrock Edition level.dat

[](#bedrock-edition-leveldat)

While the Bedrock Edition level.dat file is an uncompressed NBT file, its NBT data is prepended by two 32-bit little endian integers.

The first one seems to be the version of the Bedrock Edition Storage Tool, which is also stored in the `StorageVersion` tag of the NBT structure.

The second number is the size of the file's NBT structure (not including the two prepending integers).

A Bedrock Edition level.dat file could be read like this:

```
$data = file_get_contents("level.dat");

$version = unpack("V", $data)[1];
$dataLength = unpack("V", $data, 4)[1];

if($dataLength !== strlen($data) - 8) {
    throw new Exception("Invalid level.dat data length");
}
$tag = \Aternos\Nbt\Tag\Tag::load(new \Aternos\Nbt\IO\Reader\StringReader(substr($data, 8), \Aternos\Nbt\NbtFormat::BEDROCK_EDITION));
```

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance40

Moderate activity, may be stable

Popularity40

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 90.6% 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

Every ~44 days

Recently: every ~101 days

Total

28

Last Release

513d ago

PHP version history (3 changes)v1.2.0PHP ^7.4 || ^8.0

v1.5.0PHP >=8.0

v1.10.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/182e603c02f308d1036a1ecaba0b994665e87d13a86ff4550a96c9189a92c544?d=identicon)[aternos](/maintainers/aternos)

---

Top Contributors

[![KurtThiemann](https://avatars.githubusercontent.com/u/26512466?v=4)](https://github.com/KurtThiemann "KurtThiemann (48 commits)")[![pavog](https://avatars.githubusercontent.com/u/4786628?v=4)](https://github.com/pavog "pavog (5 commits)")

### Embed Badge

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

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

###  Alternatives

[robmorgan/phinx

Phinx makes it ridiculously easy to manage the database migrations for your PHP app.

4.5k46.2M405](/packages/robmorgan-phinx)[maennchen/zipstream-php

ZipStream is a library for dynamically streaming dynamic zip files from PHP without writing to the disk at all on the server.

1.9k286.3M147](/packages/maennchen-zipstream-php)[pocketmine/pocketmine-mp

A server software for Minecraft: Bedrock Edition written in PHP

3.5k74.6k86](/packages/pocketmine-pocketmine-mp)[paragonie/sodium_compat

Pure PHP implementation of libsodium; uses the PHP extension if it exists

930131.6M155](/packages/paragonie-sodium-compat)[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k855.0k18](/packages/danog-madelineproto)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

169425.2k8](/packages/pocketmine-bedrock-protocol)

PHPackages © 2026

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