ext-store · Reference
Limits and durability
What the store accepts and guarantees: keys of 1 to 15 bytes, string values with no NUL byte, a commit on every write, and flash that wears out if you write in a hot loop.
The rules below are what you hit in practice. On ESP32 the store is NVS flash in the phpstore partition, so
its size limits come from NVS.
Keys
| Rule | When broken |
|---|---|
| 1 to 15 bytes long (byte length, not characters), with no NUL byte | Treated as a missing key: store_set() returns false, store_get() the default. |
| Unique in the store | store_set() on an existing key overwrites it. |
Short prefixes keep keys readable inside 15 bytes: wifi.ssid, cal.x_off, boot.count.
Values
- Strings only. Store numbers with
(string)and cast back with(int)or(float). Store arrays withjson_encode()and read them withjson_decode(..., true). - No NUL bytes. A value with a NUL byte makes
store_set()returnfalseand leaves the stored value as it was (versions before 1.0.2 stored it cut at the first NUL). Encode binary data withbase64_encode()orbin2hex(). - Length. NVS caps a string at 4000 bytes including its terminator. A longer value makes
store_set()returnfalse. - Bounded total. The number of entries is bounded by the 24K partition; when it is full,
store_set()returnsfalse.
<?php
store_set('threshold', (string) 42);
$threshold = (int) store_get('threshold', '0');
store_set('cfg', json_encode(['ssid' => 'lab', 'ch' => 6]));
$cfg = json_decode(store_get('cfg', '{}'), true);
store_set('blob', base64_encode($bytes)); // raw bytes may contain NUL
$bytes = base64_decode(store_get('blob', ''));
Durability
store_set(),store_delete()andstore_clear()commit before they return. There is no flush call and no write-back cache: a value is safe the moment the call returnstrue.- NVS is built to survive a reset or a power cut during a write, leaving the old or the new value.
store_clear()removes only the script's own keys (thephpnamespace of the partition), not other NVS data.
<?php
if (store_get('mode') !== $mode) {
store_set('mode', $mode);
}
Where the calls run
| Aspect | Behaviour |
|---|---|
| Task | Every operation runs on the executor task (internal-RAM stack) because the PHP task, whose stack is in PSRAM, must not access flash. The PHP task blocks until it is done. |
| Queue timeout | A call that cannot be queued within 1000 ms fails and returns false. |
store_keys() |
The keys are gathered on the executor into a buffer that grows by doubling, then passed to PHP. An allocation or NVS error raises the exception. |
| Boot | The partition is initialised when the PHP module starts and the HAL logs persistent store ready (partition 'phpstore'). |
| Light sleep | sys_light_sleep() holds the executor, so store calls wait until it returns. |
Related
- PHP API PHP API
- Save settings Recipe
- esp32-store-hal HAL
- ext-mem (in-RAM store) Extension
- ESP-IDF NVS external