All 22 apps

CandyKv

Personal key/value store — one SQLite file per database, glob + fuzzy listing, TTL, binary-safe values

inspired by charmbracelet/skate storekey-valuepersistentdatabase

CandyKv code coverage

Personal key/value store — one SQLite database per store, @dbname namespaces, glob listing, TTL, binary values, JSON/YAML import/export, and a bare CLI.

Install

composer require sugarcraft/candy-kv

Quickstart

use SugarCraft\Kv\Store;

$store = new Store();                       // SQLite files under $XDG_CONFIG_HOME/skate (else ~/.config/skate)

$store->set('user:1', 'Alice');
$store->set('user:2', 'Bob');
echo $store->get('user:1');                 // 'Alice'
echo $store->get('missing', 'n/a');         // fallback: 'n/a'

// A key@db suffix routes to a named database ("\@" spells a literal at-sign)
$store->set('token@passwords', 'ghp_xxxx');
$store->setWithTtl('session', 'abc', 60);   // expires after 60 s

foreach ($store->list('user:*') as $entry) {  // case-sensitive character-wise glob patterns; yields Entry
    echo "{$entry->key} => {$entry->rawValue()}\n";
}
$store->listDatabases();                    // ['default', 'passwords']
$store->pruneExpired();                     // reclaims expired rows in the default database

CLI

candy-kv set color blue              # values with NUL/invalid UTF-8 auto-arm binary mode
candy-kv get color                   # prints exact stored bytes, no added newline
candy-kv list 'user-*'               # key<TAB>value rows; binary values show a <binary N bytes> placeholder
candy-kv delete 'tmp-*' --dry-run    # preview the match count without writing
candy-kv prune                       # remove expired residue
candy-kv export json > backup.json
candy-kv import json backup.json     # atomic within a database; a file spanning databases needs --no-atomic

Exit codes: 0 success, 1 miss / no match / runtime failure, 2 usage errors (unknown flags and commands are refused before anything is written). Run candy-kv --help for the full flag list.

What's in the box

SQLite storageOne SQLite file per named database under the data directory ($XDG_CONFIG_HOME/skate, else ~/.config/skate; files at 0600); key@db picks the database and reads never create files.
Glob and fuzzy listingCase-sensitive * / ? glob patterns (\* spells a literal star), reverse order, keys-only or values-only modes, and fuzzyFilter().
TTL supportExpire keys after a set time; expired rows are invisible to readers immediately and stay on disk until pruneExpired() reclaims them.
Binary values and transactionsStore raw bytes as binary entries (rawValue() decodes them) and group writes in a transaction.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Store__construct(?string $dataDir = null, string $defaultDb = 'default')Key-value store over per-database SQLite files; construction touches nothing on disk
Storeset(key, value, bool $binary = false, ?int $ttlSeconds = null) / setWithTtl(key, value, ttl)Write a key; key@db routes to a named database
Storeget(key, fallback = '') / entry(key) / suggestionFor(key)Read a value, or the full Entry, or a close-existing key for a typo
Storelist(?pattern, ?dbName, reverse, mode) / fuzzyFilter(query) / pruneExpired()Glob listing; fuzzy key ranking by local-alignment score against a query; reclaim expired rows
Storedelete(key) / setFile(key, path) / saveTo(key, path)Delete; binary values from and to files (0600)
StorelistDatabases() / deleteDatabase(name) / transaction(dbName, callable)Database management
Databaseget / raw / set / delete / deleteMany / list / allKeys / count / pruneExpired / transaction / closeOne SQLite database; raw() also sees expired rows
Entrykey, value, binary, createdAt, modifiedAt, expiresAt / isExpired() / rawValue()A stored value; rawValue() returns decoded bytes for binary entries

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.

Get / set / list

Get / set / list

File-backed store — set, get, list, delete.
Glob listing

Glob listing

List keys matching `user-*`, `user-?` and `config-*`.
Reverse-order list

Reverse-order list

List the same keys forward and in reverse key order.
Binary values

Binary values

Round-trip raw bytes in / out of the store.
Multiple DBs

Multiple DBs

Two named stores side-by-side, no collisions.

Five GIFs: glob.gif is recorded from live ./bin/candy-kv calls; the other four drive the library surface through php examples/*.php. For a text walkthrough of the CLI itself, see the Output format transcript in the README.