php-baremetal/php-esp32-sdk

SDK First-party

The esp32 SDK: boards, the PHP build recipe, runtimes, storages and the ESP-IDF toolchain for ESP32-P4 and ESP32-S3. phpbm downloads and drives it.

SDK · Reference

Memory, flash and partitions

How the PSRAM is split between PHP and the firmware, what the PHP task stack is, how the flash is partitioned, and what the optimization option costs.

Every board of the SDK has PSRAM, and the firmware refuses to build without it: PHP's memory, the PHP task stack and the OPcache cache all live there.

memory_limit

At boot the firmware reserves one block of PSRAM for PHP's memory manager, in chunks of 256 KB. The block size is memory_limit; it is always a multiple of 256 KB, at least 512 KB and at most 64 MB (256 chunks).

text how the block is sized
keep   = firmware reserve + startup + opcache-memory
chunks = (free PSRAM - keep) / 256 KB, at most 256, at least 2
memory_limit = chunks x 256 KB
Profile When Startup Firmware reserve PHP stack OPcache
Large total PSRAM of 4 MB or more startup-kb of the PHP minor, plus the startup-kb of each optional extension, plus 208 KB for packages the firmware-reserve option, at most a quarter of the free PSRAM 256 KB opcache-memory KB taken from the block
Small total PSRAM under 4 MB startup-kb of the minor plus extensions, without the 208 KB 0 (logged at boot) 128 KB disabled at boot
  • firmware-reserve (256 to 4096 KB, default 1024) is the PSRAM kept for the rest of the firmware: the network, the HTTP server, the native extensions. Raise it when a package runs out of PSRAM; lower it to give PHP more.
  • startup-kb is in sdk.json per minor (760, 816 and 872 KB for 8.3, 8.4 and 8.5) and in each extension's descriptor: see PHP versions and extensions.
  • With less than the minimum, the boot log says PSRAM too small for PHP and lists the numbers.

The boot prints the result: the first line contains memory_limit <n> KB, and the next one the free PSRAM after the start. It adds firmware reserve, opcache or PHP stack only when they differ from the defaults.

Measured memory limits (PHP 8.4 unless noted):

Board Configuration memory_limit Free PSRAM after start
waveshare-esp32-s3-eth (8 MB PSRAM) blink 5632 KB 1493 KB
waveshare-esp32-s3-eth all thirteen extensions, opcache-memory 1024 4352 KB 1562, 1477 and 1407 KB on 8.3, 8.4 and 8.5
waveshare-esp32-p4-eth (32 MB PSRAM) blink 30208 KB 1493 KB
waveshare-esp32-s3-zero (2 MB PSRAM, small profile) blink 1024 KB 85 KB
waveshare-esp32-s3-zero eleven extensions (all but mbstring and opcache), PHP 8.5 768 KB 9 KB

Outside memory_limit

Some allocations come from the PSRAM left to the firmware, not from memory_limit:

  • what PHP allocates as persistent;
  • the garbage collector's root buffer: 16 KB at start, it grows and does not shrink;
  • the SQLite page cache: up to 256 KB per open connection;
  • the memory session store: at most 64 sessions and 64 KB;
  • the zlib tables.

Large fragmented allocations can fail below memory_limit. A script that exhausts the limit ends with the usual Allowed memory size of N bytes exhausted fatal error.

Small PSRAM boards

A board with 2 MB of PSRAM (waveshare-esp32-s3-zero, espressif-esp32-s3-devkitc-1-n8r2) gets the small profile: no firmware reserve, a 128 KB stack, OPcache off. If the pool is under 1024 KB the boot logs a warning.

Measured on an ESP32-S3 with 4 MB of flash and 2 MB of quad PSRAM (board waveshare-esp32-s3-zero, PHP 8.5):

  • Eleven extensions (all but mbstring and opcache, see What fits in 4 MB of flash): memory_limit is 768 KB and the boot warns that the pool is under 1024 KB. A script starts with about 375 KB already used, and 9 KB of PSRAM stay for the rest of the firmware. A light check of each of the eleven passes, but a long script such as 12-extension-checks runs out of memory: it needs a board with more PSRAM.
  • zlib: gzuncompress() works, and so does compressing with a small window, for example deflate_init($encoding, ['window' => 9, 'memory' => 1]). gzcompress() with the default parameters fails with Allowed memory size of 786432 bytes exhausted (tried to allocate 65536 bytes), even as the first call of the script.
  • Wi-Fi: in 08-network-web/wifi-ap-s3-rgb-manage about 20 KB of PSRAM stay free after the start. Once a station joins the board's access point, the Wi-Fi buffers bring that down to about 1.2 KB. esp32-web-hal 1.0.2 and later then put HTTP requests in internal RAM; earlier versions answered every request with 503.

The PHP task stack

PHP runs on one task, pinned to core 1, with its stack in PSRAM: 256 KB (128 KB on a small board). The firmware sets zend.max_allowed_stack_size to the stack minus 16 KB, and zend.reserved_stack_size to a quarter of the stack, at least 48 KB, so a deep recursion ends in a PHP error and not in a crash.

A task with its stack in PSRAM must not touch the flash. That is the reason for the rules in Writing native packages.

Task Core Stack
main 0 16 KB on the ESP32-S3, 32 KB on the ESP32-P4; internal RAM
php 1 256 KB, PSRAM (128 KB under 4 MB of PSRAM)
executor 0 8 KB, internal RAM

Flash layout

The partition table is generated at every build. The flash size comes from the board file; the partition offsets are left to ESP-IDF, so the application sits at 0x10000.

Partition Type Size
nvs data, nvs 24K
phy_init data, phy 4K
factory app the flash, minus 128K, minus the storage partition and the package partitions, rounded down to a multiple of 64K
package partitions data as the packages declare them, after factory
storage data, fat only with embedded storage: the sources and the embedded assets

For example factory is 3840K on a 4 MB board, 7936K on 8 MB and 16128K on 16 MB or 32 MB, each with the smallest storage (128K) and no package partition.

Package partitions

A native package declares data partitions in its extra.baremetal.partitions: see Writing native packages. php-baremetal/esp32-store-hal, which backs ext-store, declares phpstore (nvs, 24K). The names factory, nvs, phy_init and storage are reserved, two packages cannot declare the same name, and each size is <n>K with n a multiple of 4.

The embedded storage image

With embedded storage the PHP sources and the embedded assets are packed into a read-only FAT image in the storage partition, written together with the application. Its size is computed from the folder phpbm prepares (the sources plus those assets, converted; see Assets):

  • each file counts in 4096-byte units, each directory and the root count 4096 bytes: used;
  • the image is used plus 64 KB plus an eighth of used, rounded up to 64K, and at least 128K.

At boot the partition is mapped into memory and mounted read-only at /app. Large images make the image, and the flash it takes from factory, grow: put them in a microsd asset folder to keep them out of flash. With microsd storage there is no storage partition: the sources live on the card and phpbm sync copies them. See Storage.

Flash sizes

Board Flash PSRAM
generic-esp32s3-quad, waveshare-esp32-s3-zero 4 MB quad
espressif-esp32-s3-devkitc-1-n8r2 8 MB quad
espressif-esp32-s3-devkitc-1-n8r8, generic-esp32s3-octal, waveshare-esp32-s3-zero-n8r8 8 MB octal
espressif-esp32-s3-devkitc-1-n16r8, freenove-esp32-s3-wroom-lite-n16r8, freenove-esp32-s3-wroom-lite-n16r16, waveshare-esp32-s3-eth, waveshare-esp32-s3-touch-lcd-1.85b 16 MB octal
generic-esp32p4, waveshare-esp32-p4-eth, waveshare-esp32-p4-pico, waveshare-esp32-p4-wifi6 32 MB hex
Note Only 16 MB are used on a 32 MB board

With the default quad flash mode, the cache maps only the first 16 MB of the flash, so the partitions stay below that limit: the upper 16 MB of a 32 MB ESP32-P4 board stay unused. A board can set flash-mode to octal on an ESP32-S3 (see Board files); no board of the SDK does.

When the sources and the package partitions leave less than 1024K for the firmware, the build stops with the project sources (...K) and the package partitions (...K) leave ...K for the firmware (at least 1024K): use a board with more flash or the microsd storage.

What fits in 4 MB of flash

On a 4 MB board the flash is the limit before the PSRAM. The factory partition is 3840K, and the app with every optional extension does not fit. Measured on waveshare-esp32-s3-zero with PHP 8.5.11 and optimization size:

What App size
The engine: Zend, standard, pcre about 853, 530 and 255 KB
mbstring, plus oniguruma for mbstring-regex 919 KB, plus 414 KB
date 534 KB
SQLite, plus pdo, pdo_sqlite and sqlite3 387 KB, plus 70 KB
opcache 63 KB
All thirteen extensions with mbstring-regex 5.18 MB: does not fit
Eleven extensions, all but mbstring and opcache 3.82 MB: fits, 108 KB left

opcache is disabled at boot under 4 MB of PSRAM anyway, so leaving it out costs nothing. To fit mbstring, leave out others that weigh as much: date and the SQLite group together weigh more than mbstring. The log option saves a little more: 75 KB at most with none in one measured project.

Firmware size and the optimization option

optimization sets the compiler optimization of the whole firmware. Measured on waveshare-esp32-s3-eth with PHP 8.4.26 and the blink project:

Value Flag Firmware PHP benchmark (lower is faster)
size -Os 2480560 B 2271 ms
performance -O2 2808512 B 2136 ms
debug -Og 2785744 B 2477 ms

performance makes the firmware about 13 percent bigger and the PHP benchmark about 6 percent faster. debug keeps the code close to the source for debugging with gdb: it is bigger and slower than size.

Size of the blink firmware by PHP minor (-Os):

Chip 8.3 8.4 8.5
ESP32-S3 about 2270 KB about 2355 KB about 2425 KB
ESP32-P4 2516 KB 2612 KB 2692 KB

With all the optional extensions, the firmware is 4767 KB on waveshare-esp32-s3-eth and 5221 KB on waveshare-esp32-p4-eth.

Last updated 2026-11-15 · v2.0.x Edit on GitHub Report issue