PHPackages                             nhanaz/blockdata - 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. [Database & ORM](/categories/database)
4. /
5. nhanaz/blockdata

AbandonedLibrary[Database & ORM](/categories/database)

nhanaz/blockdata
================

A high-performance, developer-friendly virion for storing custom data on blocks

5492[1 PRs](https://github.com/NhanAZ-Libraries/BlockData/pulls)PHPCI passing

Since Feb 12Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/NhanAZ-Libraries/BlockData)[ Packagist](https://packagist.org/packages/nhanaz/blockdata)[ RSS](/packages/nhanaz-blockdata/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

BlockData
=========

[](#blockdata)

A high-performance, developer-friendly virion for storing custom data on blocks in PocketMine-MP.

**Store any data on any block** - strings, numbers, arrays - with just 3 methods: `set()`, `get()`, `remove()`.

Features
--------

[](#features)

- **Simple API** - No custom classes, no type registration, no boilerplate
- **High Performance** - LevelDB backend with Snappy compression and in-memory caching
- **Store Anything** - Any JSON-serializable value (string, int, float, bool, array)
- **Auto Cleanup** - Optionally auto-remove data when blocks are destroyed
- **Chunk-Aware** - Cache eviction follows chunk lifecycle to prevent memory leaks
- **Multi-Plugin Safe** - Each plugin gets its own isolated LevelDB database

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

[](#installation)

**Composer:**

```
composer require nhanaz/blockdata
```

**Poggit Virion** - add to your `.poggit.yml`:

```
libs:
  - src: NhanAZ-Libraries/BlockData/BlockData
    version: ^1.0.0
```

Quick Start
-----------

[](#quick-start)

```
use NhanAZ\BlockData\BlockData;
use pocketmine\plugin\PluginBase;

class MyPlugin extends PluginBase {

    private BlockData $blockData;

    protected function onEnable(): void {
        // One-line setup - that's it!
        $this->blockData = BlockData::create($this);
    }
}
```

#### Store data

[](#store-data)

```
// Store an array
$this->blockData->set($block, [
    "owner" => $player->getName(),
    "placed_at" => time(),
    "protected" => true,
]);

// Store a simple string
$this->blockData->set($block, "Hello World");

// Store a number
$this->blockData->set($block, 42);
```

#### Read data

[](#read-data)

```
$data = $this->blockData->get($block);

if ($data !== null) {
    // Data exists! Use it.
    $player->sendMessage("Owner: " . $data["owner"]);
}

// Or use has() to check existence
if ($this->blockData->has($block)) {
    // ...
}
```

#### Remove data

[](#remove-data)

```
$this->blockData->remove($block);
```

#### Coordinate-based access

[](#coordinate-based-access)

If you have coordinates instead of a Block object:

```
$this->blockData->setAt($world, $x, $y, $z, ["key" => "value"]);
$data = $this->blockData->getAt($world, $x, $y, $z);
$exists = $this->blockData->hasAt($world, $x, $y, $z);
$this->blockData->removeAt($world, $x, $y, $z);
```

Auto Cleanup
------------

[](#auto-cleanup)

Enable automatic data removal when blocks are destroyed:

```
$this->blockData = BlockData::create($this, autoCleanup: true);
```

When enabled, block data is automatically removed on:

- **Player breaks** the block (`BlockBreakEvent`)
- **Explosions** destroy the block (`EntityExplodeEvent`)
- **Fire** burns the block (`BlockBurnEvent`)
- **Leaves** decay naturally (`LeavesDecayEvent`)

If you need custom logic (e.g. transfer data to drops), use `autoCleanup: false` and handle events yourself.

> **Note:** Auto cleanup is *event-based* and only listens to common PocketMine events.
> If other plugins modify or remove blocks in custom ways without firing these events, BlockData cannot automatically detect those changes. In that case, you should manually remove or update block data in your own code.
> See [Issue #8 – Event-Based Block Tracking Issues](https://github.com/NhanAZ-Libraries/BlockData/issues/8) for discussion and rationale.

Custom Data Path
----------------

[](#custom-data-path)

By default, BlockData stores its databases under your plugin's data folder in `blockdata/`. You can override the base path by passing a custom `$dataPath`:

```
// Store data under a custom directory
$this->blockData = BlockData::create(
    $this,
    autoCleanup: true,
    dataPath: $this->getServer()->getDataPath() . "custom-blockdata"
);
```

This will create per-world LevelDB databases under:

```
/

```

Example Plugin
--------------

[](#example-plugin)

See [BlockDataExample](https://github.com/NhanAZ-Plugins/BlockDataExample) for a full working plugin that demonstrates:

- Saving block ownership on place
- Protecting blocks from unauthorized breaking
- Inspecting block info with right-click + `/inspect` command

API Reference
-------------

[](#api-reference)

### `BlockData::create(PluginBase $plugin, bool $autoCleanup = false, ?string $dataPath = null): BlockData`

[](#blockdatacreatepluginbase-plugin-bool-autocleanup--false-string-datapath--null-blockdata)

Creates a new BlockData instance. Call once in `onEnable()`.

ParameterTypeDefaultDescription`$plugin``PluginBase`*(required)*Your plugin instance`$autoCleanup``bool``false`Auto-remove data when blocks are destroyed`$dataPath``string|null``null`Base directory for storing per-world LevelDB databases. Defaults to `/blockdata`.### Block Methods

[](#block-methods)

MethodReturnsDescription`set(Block $block, mixed $data)``void`Store data for a block`get(Block $block)``mixed`Get stored data, or `null``has(Block $block)``bool`Check if data exists`remove(Block $block)``void`Remove stored data### Coordinate Methods

[](#coordinate-methods)

MethodReturnsDescription`setAt(World, int $x, int $y, int $z, mixed $data)``void`Store data at coordinates`getAt(World, int $x, int $y, int $z)``mixed`Get data at coordinates`hasAt(World, int $x, int $y, int $z)``bool`Check data at coordinates`removeAt(World, int $x, int $y, int $z)``void`Remove data at coordinates### Data Types

[](#data-types)

You can store any JSON-serializable value:

```
$blockData->set($block, "a string");           // string
$blockData->set($block, 42);                   // int
$blockData->set($block, 3.14);                 // float
$blockData->set($block, true);                 // bool
$blockData->set($block, ["key" => "value"]);   // array
$blockData->set($block, [1, 2, 3]);            // list
$blockData->set($block, [                      // nested
    "stats" => ["hp" => 100, "mp" => 50],
    "items" => ["sword", "shield"],
]);
```

Architecture
------------

[](#architecture)

```
Your Plugin
    |
    v
BlockData          setBlockDataAt($x, $y, $z, new MyData(...));`Single flat API vs nested world/manager calls**Data model**One JSON-serializable blob per blockOne or more typed `BlockData` objects per blockCosmoverse is more flexible for multi-type per block; this library is simpler and covers most plugin use cases**Type safety**Dynamic (runtime JSON validation)Static via `BlockData` interfaceCosmoverse enforces stricter contracts; this library trades some strictness for simplicity**Auto cleanup**Built-in for 4 events (break, explode, burn, leaves decay)Not built-in (plugin must handle)Reduces boilerplate for common scenarios**Learning curve**Very low (3 core methods)Medium (NBT, factories, custom classes)Designed to be friendly for non-expert developers and editors**Extensibility**Easy to extend by adding more keys to the stored arrayEasy to extend by adding more fields to NBT classesChoice between “just add another array key” vs creating/updating a class**Best fit**Simple–medium plugins that want fast storage with minimal boilerplateComplex plugins needing multiple strongly-typed `BlockData` classes per blockBoth are production-ready; pick based on complexity and team experienceIn short, `Cosmoverse/BlockData` is an excellent, highly flexible low-level building block.
This library repackages the same core ideas into a **smaller, flatter API** that is easier to adopt quickly, without giving up LevelDB performance.

License
-------

[](#license)

LGPL-3.0-or-later

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance60

Regular maintenance activity

Popularity14

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

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

### Community

Maintainers

![](https://www.gravatar.com/avatar/737e9f0e23b56164d8e08729d58be66b69dc994c6b2bfa3c71b4efe4b231d785?d=identicon)[NhanAZ](/maintainers/NhanAZ)

---

Top Contributors

[![NhanAZ](https://avatars.githubusercontent.com/u/60387689?v=4)](https://github.com/NhanAZ "NhanAZ (40 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![kostamax27](https://avatars.githubusercontent.com/u/69608272?v=4)](https://github.com/kostamax27 "kostamax27 (1 commits)")[![MrEcstsy](https://avatars.githubusercontent.com/u/57694923?v=4)](https://github.com/MrEcstsy "MrEcstsy (1 commits)")[![poggit-bot](https://avatars.githubusercontent.com/u/22427965?v=4)](https://github.com/poggit-bot "poggit-bot (1 commits)")

---

Tags

liblibraryphppmmppocketminepocketmine-mpvirion

### Embed Badge

![Health badge](/badges/nhanaz-blockdata/health.svg)

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

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

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