PHPackages                             rafalmasiarek/php-kv - 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. rafalmasiarek/php-kv

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

rafalmasiarek/php-kv
====================

Lightweight versioned key–value storage for PHP

v1.0.0(6mo ago)02MITPHPPHP >=8.1

Since Nov 10Pushed 6mo agoCompare

[ Source](https://github.com/rafalmasiarek/php-kv)[ Packagist](https://packagist.org/packages/rafalmasiarek/php-kv)[ RSS](/packages/rafalmasiarek-php-kv/feed)WikiDiscussions main Synced 1mo ago

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

php-kv
======

[](#php-kv)

Tiny versioned key-value manager for PHP.

Concepts
--------

[](#concepts)

**Scope** + **ID** + **Key** ⇒ versioned value.

Think of:

- `scope` – logical bucket, e.g. `"user"`, `"feature"`, `"tenant"`.
- `id` – identifier inside scope, e.g. `"123"`, `"acme"`.
- `key` – name inside that document, e.g. `"theme"`, `"feature_x_enabled"`.

Example:

```
use rafalmasiarek\KV;
use rafalmasiarek\KV\Storage\FileStorage;

$storage = new FileStorage(__DIR__ . '/storage');
$kv = new KV($storage);

// create versions
$kv->set('user', '123', 'theme', 'dark');
$kv->set('user', '123', 'theme', 'light');

// read latest
$current = $kv->get('user', '123', 'theme'); // "light"

// list all latest values for given (scope,id)
$all = $kv->all('user', '123');

// detailed info (with history)
$info = $kv->info('user', '123', 'theme');
// [
//   'schema'          => 'v1',
//   'current_version' => 2,
//   'created_at'      => '2025-01-01T12:00:00+00:00',
//   'updated_at'      => '2025-01-02T09:00:00+00:00',
//   'history'         => [
//       '1' => ['value' => 'dark',  'created_at' => '...'],
//       '2' => ['value' => 'light', 'created_at' => '...'],
//   ],
// ]

// delete a key (all its versions)
$kv->delete('user', '123', 'theme');

// delete whole document (scope+id)
$kv->deleteDocument('user', '123');
```

Schema format
-------------

[](#schema-format)

Internally each `(scope, id)` document is stored as JSON:

```
{
  "schema": "v1",
  "keys": {
    "theme": {
      "schema": "v1",
      "current_version": 2,
      "created_at": "2025-01-01T12:00:00+00:00",
      "updated_at": "2025-01-02T09:00:00+00:00",
      "history": {
        "1": { "value": "dark",  "created_at": "2025-01-01T12:00:00+00:00" },
        "2": { "value": "light", "created_at": "2025-01-02T09:00:00+00:00" }
      }
    }
  }
}
```

Schemas are managed in one place: `Schema\SchemaRegistry`.

- `SchemaRegistry::CURRENT` – currently used schema id (e.g. `"v1"`).
- `SchemaRegistry::DEFINITIONS` – associative array of all supported schema versions.
- `SchemaRegistry` contains helpers used by `KV` for reading/updating documents and guarantees backwards compatibility: when you introduce `"v2"`, old `"v1"` docs continue to work and can be upgraded or appended to.

To change schema:

1. Add new entry in `SchemaRegistry::DEFINITIONS`.
2. Update `SchemaRegistry::CURRENT`.
3. Implement upgrade logic inside `SchemaRegistry` if shape changes.

Storage backends
----------------

[](#storage-backends)

All backends implement `Storage\StorageInterface`:

```
interface StorageInterface
{
    public function load(string $scope, string $id): ?array;
    public function save(string $scope, string $id, array $document): void;
    public function delete(string $scope, string $id): void;
}
```

Included:

- `FileStorage` – JSON files on disk.
- `RedisStorage` – single key per document (`kv:{scope}:{id}`).
- `MongoStorage` – one document per `(scope,id)`.

You can implement your own storage (e.g. SQL) by implementing this interface.

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

[](#installation)

```
composer require rafalmasiarek/php-kv
```

Minimal usage
-------------

[](#minimal-usage)

```
use rafalmasiarek\KV;
use rafalmasiarek\KV\Storage\FileStorage;

$kv = new KV(new FileStorage(__DIR__ . '/var/kv'));

// Set
$kv->set('app', 'flags', 'new_ui', true);

// Get
if ($kv->get('app', 'flags', 'new_ui')) {
    // ...
}
```

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance69

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

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

181d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/17765d36dfdee9f4179c94861184464cb4282d224e9db7fa86b4dff6005c166c?d=identicon)[rafalmasiarek](/maintainers/rafalmasiarek)

---

Top Contributors

[![rafalmasiarek](https://avatars.githubusercontent.com/u/36776423?v=4)](https://github.com/rafalmasiarek "rafalmasiarek (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/rafalmasiarek-php-kv/health.svg)

```
[![Health](https://phpackages.com/badges/rafalmasiarek-php-kv/health.svg)](https://phpackages.com/packages/rafalmasiarek-php-kv)
```

###  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.3k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M545](/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)