Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-store

bm-ext MIT

Persistent key-value store: survives resets and power cuts.

ext-store · PHP API

PHP API

The seven store_* functions with their real signatures. Keys are 1 to 15 bytes, values are strings, and nothing throws except store_keys().

Seven global functions. They return false rather than throw: a bad key, a value the store refuses, a store that did not open, an expired call. Check the result of store_set() while developing; a false usually means a key longer than 15 bytes. Wrong argument types and counts raise the usual TypeError and ArgumentCountError. The one exception is store_keys().

Function Returns Notes
store_set(string $key, string $value) bool Overwrites an existing key.
store_get(string $key, ?string $default = null) ?string $default when absent or invalid key.
store_has(string $key) bool
store_delete(string $key) bool false when the key did not exist.
store_clear() bool Removes every key.
store_keys() array List of key strings.
store_available() bool true once the store opened at boot.

store_set

store_set(string $key, string $value): bool

Public method. Returns bool.

Writes $value under $key and commits it to flash before returning.

Parameters

$key string required

1 to 15 bytes, with no NUL byte. Any other key returns false.

$value string required

A string with no NUL byte. Numbers, arrays and bytes need converting first; see Limits and durability.

Returns true once the value is in flash. Returns false for an invalid key, a value with a NUL byte, a store that is not available, a value NVS refuses (too long, or no room left in the partition) and a flash call that timed out.

store_get

store_get(string $key, ?string $default = null): ?string

Public method. Returns ?string.

Returns the stored string, or $default when the key is absent, invalid, or the store is not available. With no $default that is null. The default is returned as given, so it may be any value in practice, but the declared type is ?string.

store_has

store_has(string $key): bool

Public method. Returns bool.

true when the key is stored. false for an invalid key or an unavailable store.

store_delete

store_delete(string $key): bool

Public method. Returns bool.

Removes one key and commits. false when the key was not there, was invalid, or the store is not available.

store_clear

store_clear(): bool

Public method. Returns bool.

Removes every key of the script's store and commits. Takes no arguments. false when the store is not available or the erase failed.

store_keys

store_keys(): array

Public method. Returns array.

Returns the keys as a list of strings, in no particular order, and [] when the store is empty or not available. The list is collected on the executor and then handed to PHP.

Throws \Exception with the message store_keys(): cannot list the keys (out of memory or NVS error) when the keys cannot all be listed.

store_available

store_available(): bool

Public method. Returns bool.

true when the store opened at boot. Use it to guard a script that may run on a board whose partition is damaged or unreadable.

Example

php project-src/index.php: the whole API
<?php
function setup(): void
{
    if (!store_available()) {
        return;
    }

    store_set('name', 'kitchen');
    store_set('threshold', (string) 42);

    var_dump(store_get('name'));              // string(7) "kitchen"
    var_dump(store_get('missing', 'n/a'));    // string(3) "n/a"
    var_dump(store_has('threshold'));         // bool(true)
    var_dump((int) store_get('threshold'));   // int(42)
    var_dump(store_keys());                   // ['name', 'threshold'], any order

    var_dump(store_delete('name'));           // bool(true)
    var_dump(store_delete('name'));           // bool(false): already gone
    var_dump(store_set(str_repeat('k', 16), 'x')); // bool(false): key longer than 15 bytes

    store_clear();
    var_dump(store_keys());                   // array(0) {}
}

function loop(int $tick): void
{
    delay(1000);
}

Related