Package · Extension
In-RAM store
A key-value store in RAM for PHP on the board: any serializable value under a string key, shared by every request of one boot, wiped on reset. Pure extension, no HAL.
ext-mem adds seven global functions, mem_set(), mem_get(), mem_has(), mem_delete(), mem_clear(),
mem_keys() and mem_available(). The table sits in the firmware, below PHP, so what you store outlives the PHP
request that stored it. Two cases need that:
- the
web-serverruntime, where every HTTP request runs the script with fresh variables; - a counter, a cache or a latest reading that several parts of the program read.
It is a copy store, like APCu: mem_set() serializes the value and keeps the bytes, mem_get() builds a new value
from them. Nothing survives a reset; for that use ext-store.
Requirements
Pure. ext-mem needs no HAL, so conductor adds nothing for it and it builds for whatever platform your project
targets. The only requirement is php >=8.3. The extension's PHP module is mem.
Install
-
Install conductor once per machine
composer global require php-baremetal/conductorkeeps the plugin active during the first solve of a new project. -
Create the project
phpbm init my-counterwritescomposer.jsonwith conductor (^1.0, allowed as a plugin), the package registry, and the SDK, board, runtime and storage you pick. -
Require the extension
composer require php-baremetal/ext-mem -
Build and flash
phpbm flashbuilds the firmware and flashes it;phpbm monitoropens the serial console.
The resulting composer.json, for a Waveshare ESP32-S3-Touch-LCD-1.85B serving HTTP over Wi-Fi, with a script that runs once at boot to
seed the table:
{
"name": "acme/my-counter",
"type": "project",
"repositories": [
{ "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
],
"require": {
"php-baremetal/conductor": "^1.0",
"php-baremetal/ext-mem": "^1.0"
},
"config": {
"allow-plugins": { "php-baremetal/conductor": true },
"platform": { "php": "8.5.11" }
},
"extra": {
"baremetal": {
"sdk": "esp32@^2.0",
"board": "waveshare-esp32-s3-touch-lcd-1.85b",
"runtime": "web-server",
"storage": "embedded",
"options": { "init": "init.php" }
}
}
}
A first script
project-src/index.php runs once per HTTP request. A plain PHP variable would restart at 0 every time; the counter
in mem_* does not.
<?php
$hits = (int) mem_get('hits', 0) + 1;
mem_set('hits', $hits);
header('Content-Type: text/plain');
echo "request #$hits since boot\n";
PHP API at a glance
| Function | Returns | Meaning |
|---|---|---|
mem_set(string $key, mixed $value) |
bool |
Store a serialized copy. Empty key gives false. |
mem_get(string $key, mixed $default = null) |
mixed |
A fresh copy, or $default. |
mem_has(string $key) |
bool |
Is the key present. |
mem_delete(string $key) |
bool |
true when the key existed. |
mem_clear() |
bool |
Drop every key. |
mem_keys() |
array |
The keys, in insertion order. |
mem_available() |
bool |
true whenever the extension is built in. |
Details: PHP API and Values and lifetime.
Notes
- Wiped on reset. A reset, power loss, crash or wake from deep sleep starts with an empty table. A
sys_light_sleep()resumes the program where it stopped, so the table stays. - No flash. Nothing touches flash, so there is no wear and no executor call; everything runs on the PHP task.
- No limits but RAM. No cap on key length, value size or entry count. A table that grows without bound ends in an out-of-memory failure of the whole program; see Values and lifetime.
- No locking. PHP runs one script at a time, so a read-modify-write inside one request cannot interleave with another.
Related
- PHP API PHP API
- Values and lifetime Reference
- ext-store (persistent store) Extension
- ext-hello Extension