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
-
$keystringrequired 1 to 15 bytes, with no NUL byte. Any other key returns
false.-
$valuestringrequired 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
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
- Limits and durability Reference
- Count boots Recipe
- Save settings Recipe