Built-in extension API
The native (C) extensions that come with the firmware and expose the board's hardware and runtime to PHP. This is the reference for their functions as of the 1.0 API.
Two groups:
- Always compiled in —
gpio,sys,mem,store. Available in every build; no config needed. - Opt-in —
wifi. Compiled in only when the project enables it ([extensions.wifi] enabled = true), because it carries weight.
Every extension exposes a <name>_available() probe that returns true when the extension is
compiled in and its preconditions are met. Because an absent extension's functions don't exist at all,
pair it with function_exists() when a build might not include it:
All functions carry typed signatures (arguments and return types), so they participate in reflection and the usual PHP type coercion.
gpio — pins and timing
Always compiled in.
Constants: GPIO_INPUT, GPIO_OUTPUT. Timing lives in sys — use sys_delay() (or its delay()
alias) to pause.
mem — in-RAM key/value store (per boot)
Always compiled in. A volatile store shared across the requests of a single boot (the RAM twin of
store_*). See In-RAM store.
store — persistent key/value store (survives reboot)
Always compiled in, but active only when the project reserves a store partition
([store] size_kb = N); without it, store_available() returns false and the setters are inert.
See Persistent store.
sys — system and runtime
Always compiled in. Timing, reboot and reset info, chip/board identity, and memory introspection.
(The memory functions report the real ESP-IDF heap, which PHP's own memory_get_usage() can't on this
port — with USE_ZEND_ALLOC=0 the Zend heap lives in PSRAM via malloc, so it reads 0.)
delay(int $ms): void is a plain alias of sys_delay(), kept for the Arduino-style idiom. The
unprefixed psram_free(), psram_size(), psram_largest_free(), heap_free(), heap_size() still
work but are deprecated (they emit E_DEPRECATED); use the sys_ names.
wifi — scan, join, or create a network
Opt-in ([extensions.wifi] enabled = true), on WiFi-capable SoCs (ESP32 / ESP32-S3 / C-series, or an
ESP32-P4 with a companion over ESP-HOSTED). Credentials are passed at runtime, never baked in.
wifi_scan() returns false on a scan failure (not an empty array), so guard it:
Addressable LEDs (WS2812, SK6812) are a separate opt-in extension, led, with a per-chip driver class
(Baremetal\Led\Driver\*) rather than global functions — the pin and pixel count are passed at
construction. See the s3-rgb-show example.
To confirm a build's extensions actually work on real hardware, flash the
ext-selftest example: it exercises every function above and reports
PASS/FAIL on the serial log.