php-api.md

eyebrow	Package · Extension
lede	Every function ext-sys adds: fifteen sys_* functions, the delay() alias and five deprecated memory aliases. The strings and limits below are those of the ESP32 provider.
see_also	href meta ../overview.md 3 min href meta ../recipes/health-report.md Recipe href meta ../recipes/measure-elapsed-time.md Recipe href meta ../recipes/restart-on-condition.md Recipe href meta label package:php-baremetal/esp32-sys-hal HAL esp32-sys-hal
prev	label href Overview ../overview.md
next	label href Print a health report ../recipes/health-report.md

PHP API

All functions are global. Except sys_delay() and delay(), none takes an argument; passing one throws ArgumentCountError. The extension defines no classes and no constants.

Function	Returns	Meaning
sys_delay(int $ms)	void	Sleep $ms milliseconds, yielding the core.
delay(int $ms)	void	Alias of sys_delay().
sys_uptime_ms()	int	Milliseconds since boot.
sys_micros()	int	Microseconds since boot.
sys_restart()	void	Reboot the chip. Does not return.
sys_reset_reason()	string	Why the chip last booted.
sys_chip_model()	string	Chip model, e.g. "ESP32-S3".
sys_cpu_freq_mhz()	int	Configured CPU frequency in MHz.
sys_mac()	string	MAC address as aa:bb:cc:dd:ee:ff.
sys_idf_version()	string	SDK version the firmware was built with.
sys_heap_free()	int	Free internal RAM, bytes.
sys_heap_size()	int	Total internal RAM pool, bytes.
sys_psram_free()	int	Free PSRAM, bytes.
sys_psram_size()	int	Total PSRAM pool, bytes.
sys_psram_largest_free()	int	Largest contiguous free PSRAM block, bytes.
sys_available()	bool	Always true.

PHP integers are 32-bit on the board (PHP_INT_MAX is 2147483647). The clock behind both functions is truncated to that size, so sys_micros() jumps to a large negative value after about 35.8 minutes of uptime, and sys_uptime_ms() after about 24.8 days. Never compare raw readings across that point; compute differences as shown in Measure elapsed time safely.

Timing

sys_delay

Blocks the script for $ms milliseconds by suspending its task, so other tasks run and the watchdog stays fed. It is never a busy-wait. The resolution is one scheduler tick (10 ms at the ESP-IDF default of 100 Hz): the wait is rounded down to whole ticks, so a delay shorter than one tick returns almost at once.

Milliseconds to sleep. Negative values are treated as 0.

delay

The same function as sys_delay() under the Arduino-style name. It is not deprecated; use whichever reads better.

Milliseconds to sleep. Negative values are treated as 0.

sys_uptime_ms

Milliseconds since boot. Monotonic until it wraps to a negative value after about 24.8 days. Use it for anything measured in seconds or longer.

sys_micros

Microseconds since boot, from the same clock. It wraps to a negative value after 2^31 µs (about 35.8 minutes) and keeps counting from there, so use it only for short intervals.

Control

sys_restart

Reboots the chip immediately. It never returns: no PHP code after the call runs, and no shutdown functions or destructors execute. After the reboot sys_reset_reason() reports "software".

sys_reset_reason

Why the chip last booted. On ESP32 one of:

Value	Meaning
poweron	Power was applied.
external	The external reset pin was pulled.
software	A software reboot, e.g. sys_restart().
panic	A crash (exception or panic).
int_wdt	The interrupt watchdog fired.
task_wdt	The task watchdog fired, typically a loop that never sleeps.
wdt	Another watchdog fired.
deepsleep	Woke from deep sleep.
brownout	The supply voltage dropped too low.
sdio	Reset over SDIO.
unknown	Any other reason.

Identity

sys_chip_model

The chip model. On ESP32 one of "ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C2", "ESP32-C6", "ESP32-H2", "ESP32-P4", or "unknown" for anything else.

sys_cpu_freq_mhz

The CPU frequency the firmware was configured with, in MHz (e.g. 240). It is the configured value, not a measurement: if power management scales the clock down, the number does not change.

sys_mac

The MAC address as 17 lowercase characters, aa:bb:cc:dd:ee:ff. On ESP32 it is the Wi-Fi station MAC, derived from the factory-burned address, so it is unique per chip and stable across reboots: a good device ID.

sys_idf_version

The SDK version the firmware was built with. On ESP32 it is the ESP-IDF version, e.g. "v5.3.1".

Memory

The memory functions read two pools: internal RAM and external PSRAM. All values are in bytes. On a board without PSRAM every sys_psram_* function returns 0.

PHP values are allocated from the chip's heap, in PSRAM when the board has it. memory_get_usage() does not see that heap; sys_psram_free() (or sys_heap_free() without PSRAM) does.

sys_heap_free

Free internal RAM right now.

sys_heap_size

Total size of the internal RAM heap. It is smaller than the chip's SRAM figure on the datasheet, because static data and stacks sit outside the heap.

sys_psram_free

Free PSRAM right now. 0 without PSRAM.

sys_psram_size

Total size of the PSRAM heap. 0 without PSRAM.

sys_psram_largest_free

The largest single block that can still be allocated from PSRAM. Compare it with sys_psram_free(): a large gap means the pool is fragmented, and a big allocation (a large string or array) can fail even though enough memory is free in total.

Presence

sys_available

Returns true. When ext-sys is not in the firmware the function does not exist at all, so test with function_exists():

<?php
if (!function_exists('sys_available')) {
    echo "ext-sys is not in this firmware\n";
    return;
}

Deprecated aliases

The unprefixed memory names still work, but every call emits an E_DEPRECATED notice. Switch to the sys_ names.

They return exactly what their sys_ counterparts return. No removal version is set; new code should not use them.

Deprecated	Use instead
heap_free(): int	sys_heap_free()
heap_size(): int	sys_heap_size()
psram_free(): int	sys_psram_free()
psram_size(): int	sys_psram_size()
psram_largest_free(): int	sys_psram_largest_free()