Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-mem

bm-ext MIT

In-RAM key-value store: shared across requests, wiped on reset.

needs no platform HAL

ext-mem · PHP API

PHP API

The seven mem_* functions with their real signatures. All work on one table shared by every request; each value goes in and comes out through PHP serialization, so every read is an independent copy.

Seven global functions. Keys are any non-empty string: no length cap, no character restriction, binary-safe. The empty string is rejected by every key-taking function. None of them raise an error for a missing key or an empty table; wrong argument types and counts raise the usual TypeError and ArgumentCountError.

Function Returns Notes
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 if absent, empty key or unreadable.
mem_has(string $key) bool Is the key present. Empty key gives false.
mem_delete(string $key) bool true if the key existed and was removed.
mem_clear() bool Drop every key; true.
mem_keys() array List of stored keys (strings), in insertion order.
mem_available() bool true whenever the extension is built in.

mem_set

mem_set(string $key, mixed $value): bool

Public method. Returns bool.

Serializes $value and stores it under $key, replacing any previous value. Returns true on success, false for an empty key or a value that serialized to nothing. What is stored is a snapshot: changing the variable afterwards does not change the store.

Parameters

$key string required

Non-empty key. An int passed here is coerced to its string form unless strict_types is on.

$value mixed required

Any value serialize() accepts: null, scalars, arrays, objects of serializable classes.

mem_get

mem_get(string $key, mixed $default = null): mixed

Public method. Returns mixed.

Rebuilds the value stored under $key as a new, independent PHP value and returns it. Returns $default when the key is absent, when $key is empty, or when the stored bytes cannot be unserialized. Each call builds a new copy; changing it does not touch the store until you mem_set() it back.

Parameters

$key string required

The key to read.

$default mixed optional, default null

Returned when there is nothing readable under the key.

A stored null and a missing key both give null with the default $default; use mem_has() to tell them apart. The same goes for a stored false and a false default. Objects are rebuilt with the normal unserialize rules (__unserialize and __wakeup run); the class must be defined or autoloadable in the reading request, otherwise you get a __PHP_Incomplete_Class.

mem_has

mem_has(string $key): bool

Public method. Returns bool.

true if $key is in the table, false otherwise or for an empty key. It does not read the value, so it is true even for a stored value mem_get() cannot rebuild.

mem_delete

mem_delete(string $key): bool

Public method. Returns bool.

Removes $key and frees its memory. Returns true if the key existed and was removed, false if it did not exist or the key is empty.

mem_clear

mem_clear(): bool

Public method. Returns bool.

Removes every key and frees every value. Takes no arguments. Returns true.

mem_keys

mem_keys(): array

Public method. Returns array.

Returns a list (0 to n-1) of the keys currently stored, as strings, in insertion order. Overwriting a key keeps its position; deleting and setting it again moves it to the end. Numeric-looking keys stay strings ('42', not 42). Returns [] when the table is empty.

mem_available

mem_available(): bool

Public method. Returns bool.

Returns true. There is nothing to configure or mount, so unlike store_available() it never reports a disabled store. Its practical use is behind a function_exists('mem_available') check, to detect a firmware built with ext-mem.

Example

php project-src/index.php: the whole API
<?php
mem_set('greeting', 'hello');
mem_set('cfg', ['unit' => 'C', 'every' => 5]);
mem_set('nothing', null);

var_dump(mem_get('cfg')['unit']);        // string(1) "C"
var_dump(mem_get('missing', 'n/a'));     // string(3) "n/a"
var_dump(mem_has('nothing'));            // bool(true): a stored null
var_dump(mem_keys());                    // ['greeting', 'cfg', 'nothing']

$cfg = mem_get('cfg');
$cfg['every'] = 10;                      // a copy: the store is unchanged
mem_set('cfg', $cfg);                    // publish the change

var_dump(mem_delete('greeting'));        // bool(true)
var_dump(mem_delete('greeting'));        // bool(false): already gone
mem_clear();
var_dump(mem_keys());                    // array(0) {}

Related