{"id":19826239,"url":"https://github.com/aternosorg/php-nbt","last_synced_at":"2025-05-08T21:21:28.188Z","repository":{"id":48880056,"uuid":"402460196","full_name":"aternosorg/php-nbt","owner":"aternosorg","description":"A full PHP implementation of Minecraft's Named Binary Tag (NBT) format.","archived":false,"fork":false,"pushed_at":"2024-12-21T18:53:33.000Z","size":99,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-08T00:11:44.275Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aternosorg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-02T14:54:48.000Z","updated_at":"2025-01-03T11:59:16.000Z","dependencies_parsed_at":"2023-11-13T13:45:49.991Z","dependency_job_id":"4e7666e9-3761-4953-958a-6333c0904e6d","html_url":"https://github.com/aternosorg/php-nbt","commit_stats":{"total_commits":37,"total_committers":3,"mean_commits":"12.333333333333334","dds":0.08108108108108103,"last_synced_commit":"fc8fa6022faf105de082636758c64937b266897b"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-nbt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-nbt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-nbt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fphp-nbt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/php-nbt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253150078,"owners_count":21861830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T11:09:50.672Z","updated_at":"2025-05-08T21:21:28.168Z","avatar_url":"https://github.com/aternosorg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# php-nbt\nA full PHP implementation of Minecraft's Named Binary Tag (NBT) format.\n\nIn contrast to other implementations, this library provides full support\nfor 64-bit types, including the relatively new `TAG_Long_Array`.\n\nAdditionally, all three flavors (Java Edition, Bedrock Edition/little endian, and Bedrock Edition/VarInt) of the NBT format are supported.\n\n### Installation\n```shell\ncomposer require aternos/nbt\n```\n\n## Usage\n### Reading NBT data\nTo read existing NBT data, a Reader object is required.\nThis library implements different readers to read NBT data from strings.\n```php\n//Read uncompressed NBT data\n$reader = new \\Aternos\\Nbt\\IO\\Reader\\StringReader(\"...nbtData...\", \\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION);\n\n//Read gzip compressed NBT data\n$gzipReader = new \\Aternos\\Nbt\\IO\\Reader\\GZipCompressedStringReader(\"...compressedNbtData...\", \\Aternos\\Nbt\\NbtFormat::JAVA_EDITION);\n\n//Read zlib compressed NBT data\n$zlibReader = new \\Aternos\\Nbt\\IO\\Reader\\ZLibCompressedStringReader(\"...compressedNbtData...\", \\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION_NETWORK);\n```\nNote that the reader object is also used to specify the NBT format flavor. \nAvailable are `\\Aternos\\Nbt\\NbtFormat::JAVA_EDITION`, `\\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION`, and `\\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION_NETWORK`.\n\nMore advanced readers can be created by implementing the `\\Aternos\\Nbt\\IO\\Reader\\Reader` interface or by extending the `\\Aternos\\Nbt\\IO\\Reader\\AbstractReader` class.\n\nA reader object can be used to load the NBT tag.\n```php\n$reader = new \\Aternos\\Nbt\\IO\\Reader\\StringReader(\"...nbtData...\", \\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION);\n\n$tag = \\Aternos\\Nbt\\Tag\\Tag::load($reader);\n```\nIn theory, any type of NBT tag could be returned, but in reality all NBT files\nwill start with either a compound tag or a list tag.\n\n### Manipulating NBT structures\nTag values of type `TAG_Byte`, `TAG_Short`, `TAG_Int`, `TAG_Long`, `TAG_Float`,\n`TAG_Double`, `TAG_String` can be accessed via their `getValue()` and `setValue()` functions.\n```php\n$myInt new \\Aternos\\Nbt\\Tag\\IntTag();\n\n$myInt-\u003esetValue(42);\necho $myInt-\u003egetValue(); // 42\n```\n\nOn String tags, `getValue()` and `setValue()` use the UTF-8 encoding and convert strings based on the selected NBT flavor \nwhen being serialized.\n\n\nCompound tags, list tags, and array tags implement the `ArrayAccess`, `Countable`,\nand `Iterator` interfaces and can therefore be accessed as arrays.\n```php\n$myCompound = new \\Aternos\\Nbt\\Tag\\CompoundTag();\n\n$myCompound[\"myInt\"] = (new \\Aternos\\Nbt\\Tag\\IntTag())-\u003esetValue(42);\n$myCompound[\"myFloat\"] = (new \\Aternos\\Nbt\\Tag\\IntTag())-\u003esetValue(42.42);\necho count($myCompound); // 2\n\n//Manually setting a list's type is not strictly necessary,\n//since it's type will be set automatically when the first element is added\n$myList = (new \\Aternos\\Nbt\\Tag\\ListTag())-\u003esetContentTag(\\Aternos\\Nbt\\Tag\\TagType::TAG_String);\n\n$myList[] = (new \\Aternos\\Nbt\\Tag\\StringTag())-\u003esetValue(\"Hello\");\n$myList[] = (new \\Aternos\\Nbt\\Tag\\StringTag())-\u003esetValue(\"World\");\n```\n\nAlternatively, compound tags can be accessed using getter/setter functions. This is especially useful in combination with\nthe new PHP null safe operator.\n```php\n/** @var \\Aternos\\Nbt\\Tag\\CompoundTag $playerDat */\n$playerDat = \\Aternos\\Nbt\\Tag\\Tag::load($reader);\n\n$playerDat-\u003eset(\"foo\", (new \\Aternos\\Nbt\\Tag\\StringTag())-\u003esetValue(\"bar\")); //Set a value\n$playerDat-\u003edelete(\"foo\"); //Delete a value\n\n$playerName = $playerDat-\u003egetCompound(\"bukkit\")?-\u003egetString(\"lastKnownName\")?-\u003egetValue();\necho $playerName ?? \"Unknown player name\";\n```\n\n### Serializing NBT structures\nSimilar to the reader object to read NBT data, a writer object is required\nto write NBT data.\n```php\n//Write uncompressed NBT data\n$writer = (new \\Aternos\\Nbt\\IO\\Writer\\StringWriter())-\u003esetFormat(\\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION);\n\n//Write gzip compressed NBT data\n$gzipWriter = (new \\Aternos\\Nbt\\IO\\Writer\\GZipCompressedStringWriter())-\u003esetFormat(\\Aternos\\Nbt\\NbtFormat::JAVA_EDITION);\n\n//Write zlib compressed NBT data\n$gzipWriter = (new \\Aternos\\Nbt\\IO\\Writer\\ZLibCompressedStringWriter())-\u003esetFormat(\\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION_NETWORK);\n```\nThe NBT flavor used by a writer object can differ from the one used by the \nreader object that was originally used to read the NBT structure.\nIt is therefore possible to use this library to convert NBT structures between the different formats.\n\nMore advanced writers can be created by implementing the `\\Aternos\\Nbt\\IO\\Writer\\Writer` interface or by extending the `\\Aternos\\Nbt\\IO\\Writer\\AbstractWriter` class.\n\nA writer object can be used to write/serialize an NBT structure.\n```php\n$writer = (new \\Aternos\\Nbt\\IO\\Writer\\StringWriter())-\u003esetFormat(\\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION);\n\n$tag-\u003ewrite($writer);\nfile_put_contents(\"data.nbt\", $writer-\u003egetStringData());\n```\n\n### Bedrock Edition level.dat\nWhile the Bedrock Edition level.dat file is an uncompressed NBT file, \nits NBT data is prepended by two 32-bit little endian integers.\n\nThe first one seems to be the version of the Bedrock Edition Storage Tool, \nwhich is also stored in the `StorageVersion` tag of the NBT structure.\n\nThe second number is the size of the file's NBT structure (not including the two prepending integers).\n\nA Bedrock Edition level.dat file could be read like this:\n```php\n$data = file_get_contents(\"level.dat\");\n\n$version = unpack(\"V\", $data)[1];\n$dataLength = unpack(\"V\", $data, 4)[1];\n\nif($dataLength !== strlen($data) - 8) {\n    throw new Exception(\"Invalid level.dat data length\");\n}\n$tag = \\Aternos\\Nbt\\Tag\\Tag::load(new \\Aternos\\Nbt\\IO\\Reader\\StringReader(substr($data, 8), \\Aternos\\Nbt\\NbtFormat::BEDROCK_EDITION));\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-nbt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fphp-nbt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fphp-nbt/lists"}