Key/Value Storage

About 2 min

Key/Value Storage

Warlock can operate as a simple key/value storage system, also known as an in-memory database, similar to applications such as Redis and Memcached.

The Key/Value Store (KVStore) runs within the memory of the Warlock Server process. This architecture allows for exceptionally fast access since data is managed directly by the central process responsible for handling connections and signals.

Features

The PHP Server and JavaScript Client: Efficiently transfer data between the backend and the frontend.
Warlock Services: Allow independent, long-running services to coordinate and share data.
Event Handlers: Store and retrieve context within event-driven workflows, ensuring state persistence across asynchronous events.

Configuration

The KVStore feature is disabled by default. To use it, you must enable it in your Warlock configuration (typically warlock.json or within your application configuration).

PHP (Recommended)

<?php
return [
    'kvstore' => [
        'enabled' => true,
    ],
];

JSON

{
    "kvstore": {
        "enabled": true
    }
}

INI (Legacy)

[kvstore]
enabled = true

Persistence

By default, the KVStore is purely in-memory, meaning data is lost when the Warlock server restarts. You can enable persistence to save data to disk.

PHP (Recommended)

<?php
return [
    'kvstore' => [
        'enabled' => true,
        'persist' => true,
        'compact' => 3600,
    ],
];

JSON

{
    "kvstore": {
        "enabled": true,
        "persist": true,
        "compact": 3600
    }
}

INI (Legacy)

[kvstore]
enabled = true
persist = true
compact = 3600

enabled: Set to true to enable the KVStore.
persist: Set to true to enable disk persistence.
compact: Time in seconds between database compactions (default: 3600).

Usage

The KVStore is accessed via the Hazaar\Warlock\Client class.

Connecting

First, instantiate the client and connect to the Warlock server.

use Hazaar\Warlock\Client;

$warlock = new Client();
$warlock->connect();

Basic Operations

Set and Get Values

You can store any serializable PHP value (strings, arrays, objects, etc.). The set method also accepts an optional timeout (TTL) in seconds.

// Store a value
$warlock->set('my_key', 'some value');

// Store a value with a 60-second expiration
$warlock->set('temp_key', 'transient value', 60);

// Retrieve a value
$value = $warlock->get('my_key');
echo $value; // Outputs: 'some value'

Check Existence and Delete

// Check if a key exists
if ($warlock->has('my_key')) {
    // Delete the key
    $warlock->del('my_key');
}

Pull (Retrieve and Delete)

The pull method retrieves a value and immediately removes it from the store.

$value = $warlock->pull('my_key');

Clear All Data

To remove all data from the KVStore (or a specific namespace):

$warlock->clear();

Namespaces

All KVStore methods support an optional namespace argument. This allows you to group keys logically and avoid collisions.

// Set value in 'users' namespace
$warlock->set('user_123', ['name' => 'John'], null, 'users');

// Get value from 'users' namespace
$user = $warlock->get('user_123', 'users');

// Clear only the 'users' namespace
$warlock->clear('users');

Note: Operations without a namespace use the global namespace.

List Operations

The KVStore supports list-style operations (queues and stacks).

Push and Pop

Add elements to the end of a list and remove them from the end.

// Push items to a list
$warlock->push('my_list', 'item1');
$warlock->push('my_list', 'item2');

// Pop item from the end
$item = $warlock->pop('my_list'); // Returns 'item2'

Shift and Unshift

Add elements to the start of a list and remove them from the start.

// Unshift item to the start
$warlock->unshift('my_list', 'start_item');

// Shift item from the start
$item = $warlock->shift('my_list'); // Returns 'start_item'

Incr and Decr

Increment or decrement integer values atomically.

$warlock->set('counter', 10);

$newVal = $warlock->incr('counter'); // 11
$newVal = $warlock->incr('counter', 5); // 16

$newVal = $warlock->decr('counter'); // 15

Inspection

List Keys and Key-Value Pairs

// Get all keys
$keys = $warlock->keys();

// Get all keys in a namespace
$userKeys = $warlock->keys('users');

// Get all values (warning: can be large)
$values = $warlock->vals();

// Get all key-value pairs as an associative array
$allData = $warlock->list();

Count Elements

The count method works differently depending on the context:

It counts the number of items in a list/array stored at a specific key.
It does not count the total number of keys in the store (use keys() and count the result).

$warlock->push('my_list', 'a');
$warlock->push('my_list', 'b');

// Count items in the 'my_list' key
$count = $warlock->count('my_list'); // Returns 2