OPcache

Without an opcode cache, PHP recompiles every script on every request: tokenize, parse, compile, optimize. For one small script that is cheap. For a framework that pulls in hundreds of files it dominates the request time. Zend OPcache caches the compiled bytecode so the next run skips all of that.

This is a real port of the bundled ext/opcache, not a stub, verified on ESP32-P4 hardware. It is built without JIT (unsupported on these targets) and statically linked into the firmware, running in one of two cache modes.

Two cache modes

The port keeps the bytecode either on the microSD or in PSRAM. The two modes differ only in where the compiled bytecode lives and what that costs, not in what OPcache does with it.

Enabling it

OPcache is opt-in per project. Turn it on in the project config; the mode is chosen at build time by the in_memory setting.

[extensions.opcache]
enabled = true
# in_memory defaults to false: the cache lives on the card

[extensions.opcache]
enabled = true
in_memory = true   # keep the cache in PSRAM instead of on the card (small apps only)

At the build layer these map to two CMake options: PHP_EXT_OPCACHE compiles OPcache in, and PHP_EXT_OPCACHE_SHM (the in_memory setting) selects the PSRAM shared-memory backend instead of the file cache. On boot the firmware logs which mode it took: opcache: file cache at /sdcard/opcache or opcache: in-RAM (PSRAM SHM) bytecode cache.

Why the file cache is the default

The bytecode cache and PHP's per-request heap both live in PSRAM. A framework the size of Laravel needs roughly 16 to 20 MB of heap per request, and its compiled bytecode is well over 12 MB. Reserving enough PSRAM to hold the bytecode in RAM leaves too little for the request, so it runs out of memory. The file cache sidesteps this by keeping the bytecode on the card and leaving the whole PSRAM for the request. For a small app whose bytecode plus heap fit comfortably, in_memory is faster, since after warm-up it touches neither the compiler nor the SD.

That headroom argument is sharper on the smaller boards. On the ESP32-P4 with 32 MB of PSRAM, a framework still does not fit in-memory, so it uses the file cache; on the ESP32-S3 with 8 MB, only genuinely small apps have room for the in-memory cache at all.

Measured speedup

On the ESP32-P4, the file-cache OPcache takes the laravel-demo-optimized welcome page from about 12 s to about 8.4 s per request. What remains is SD reads of the bytecode plus execution; the compile is gone.

The gain is the compile step, which for a large framework is most of the request. What is left over is the bytecode read plus execution, so in_memory (which also drops the read) only helps further when the app is small enough to fit.

Using it in practice

1. 01

   Warm the cache.

   The first request after the cache is empty compiles and writes it, so it is as slow as no cache, or a touch slower. Every request after that is fast.

2. 02

   Change code, then invalidate.

   validate_timestamps is off, so OPcache does not check file mtimes and will keep using stale bytecode after you edit the source. Clear the cache to pick up the change: delete /sdcard/opcache in file mode, or reboot the board in in-memory mode.

3. 03

   Keep a writable card in file mode.

   The file cache needs a writable microSD; in_memory mode needs no card.

Seeded ini directives

OPcache's directives are PHP_INI_SYSTEM and have to be set before the engine starts, so they cannot come from a runtime ini_set(). The firmware seeds them through the embed SAPI's ini_defaults hook in main.c, before php_embed_init() reads the ini. These are set in both modes:

The file-cache mode adds:

The in-RAM (in_memory) mode adds instead:

How the port works

OPcache is not an ordinary PHP module. It is a Zend extension that hooks the compiler, and it assumes a full Unix underneath. The adaptations for this target:

• Static registration. There is no opcache.so to dlopen, and this build sets ZEND_EXTENSIONS_SUPPORT == 0 (no libdl), so zend_register_extension() is a no-op. The firmware runs OPcache's zend_extension startup directly, before zend_startup_extensions() (patch 0006, keyed on the PHP_EXT_OPCACHE_ENABLED marker). The same patch teaches accel_find_sapi() the embed SAPI, so opcache.enable_cli=1 turns it on.
• No RTC. The board boots at the 1970 epoch while the card's files are dated in the future, so OPcache's "file too new to cache" guard would skip every file. The firmware sets opcache.file_update_protection=0, which is safe because validate_timestamps is off as well.
• POSIX gaps. picolibc lacks sys/ipc.h, sys/shm.h, sys/mman.h and some symbols (mmap, writev, setuid). Stub headers plus weak no-op symbols cover the SHM and restart code paths that never run in either cache mode (compat/opcache_stubs/, compat/opcache_posix_stubs.c); writev gets a real write()-loop implementation, because the file-cache writer uses it.
• PSRAM shared memory. The in_memory mode needs a shared-memory backend, but there is no mmap and no System V SHM. Since the firmware is a single process with the engine kept alive across requests, "shared" memory is just a plain PSRAM allocation that outlives the request. It is compiled in as the USE_MALLOC_SHM backend (compat/shared_alloc_malloc.c) and patch 0007, which also no-ops the file-lock based locking: one task serves one request at a time.