Overview
The firmware that is the PHP port: the real, unmodified Zend engine from php.net, cross-compiled for the ESP32 and running your index.php on the chip — the same interpreter, opcode by opcode.
php-esp32 runs the official PHP interpreter on microcontrollers. It is not a reimplementation,
a language subset, or a transpiler: the upstream Zend engine from php.net is
cross-compiled for the chip and executes your index.php opcode by opcode, the same way it would
behind a web server.
The source tree is vendored unchanged; the only modifications are separate patches applied at build
time, for the handful of places where a bare-metal RTOS differs from a Unix host. Hand the same
script to this engine or to a desktop php and you get the same output — because underneath it is
the same interpreter.
What real PHP means here
Namespaces, classes, interfaces, traits, enums, closures, generators, match, exceptions, typed
properties and attributes — plus strings, arrays, math, JSON, PCRE, hashing, SPL, Reflection and the
CSPRNG. Composer works with unmodified packages from Packagist, and on the ESP32-P4 stock Laravel
and Symfony serve pages over HTTP.
The shape of a project
A project is a folder with a small php-esp32.config.toml and a project-src/ holding your PHP. You
write the code; phpflash scaffolds, builds, flashes
and monitors it.
<?php
// runs once at boot
function setup(): void {
gpio_mode(2, GPIO_OUTPUT);
}
// runs forever, Arduino-style
function loop(): void {
gpio_write(2, 1); delay(500);
gpio_write(2, 0); delay(500);
}There are three execution models — a plain run-once script, the setup() / loop() sketch above,
and a per-request web-server model — covered in Getting started.
Hardware today
| Family | Core | PSRAM | Networking |
|---|---|---|---|
| ESP32-P4 | dual-core RISC-V, up to 400 MHz | up to 32 MB | Ethernet on the -eth boards |
| ESP32-S3 | dual-core Xtensa LX7, 240 MHz | 8 MB | Ethernet (W5500) on the -eth boards |
PHP 8.3, 8.4 and 8.5 coexist in the tree and are selectable per project. A new chip family is a
directory under boards/, not a change to the engine.
Where to go next
- Getting started — install the tools, scaffold, flash your first board.
- Architecture — memory, the execution models, how PHP is embedded.
- Extensions — what is built in, what is optional, what is not ported.
- Storage & state — microSD vs embedded, the
store_*andmem_*KV stores, and a baked-in.env. - Reference — flash/RAM footprint and the deep porting notes.