Extension
A native PHP extension in C: the functions and classes you call. It declares its module (and a priority), requires the <x>-hal virtuals it needs and may declare registries for drivers.
ext-gpio · ext-i2cA firmware project is its composer.json. Composer, with the conductor plugin, decides which packages go in and binds each one to the chip's platform. phpbm fetches the SDK and drives the build. This registry hosts the bm-* packages.
Each piece has one job, and each one lives in its own place.
composer install resolves the packages and runs conductor, which puts the bm-* packages under .phpbm/. phpbm build reads what conductor wrote, resolves the SDK pinned in phpbm.lock and hands a build plan to the SDK, which generates an ESP-IDF project and compiles it. phpbm flash writes the result to the board.
Composer and conductor decide what goes in; phpbm and the SDK decide how it is built.
# or the PHAR from github.com/php-baremetal/phpbm/releases
composer global require php-baremetal/phpbm
# active while Composer resolves: binds the -hal virtuals
composer global require php-baremetal/conductor
# the SDK, from its GitHub release
phpbm sdk:install esp32
# composer.json, project-src/, this registry, SDK and board
phpbm init
composer require php-baremetal/ext-gpio
# offers toolchain:install the first time
phpbm build
# build, check the chip, flash
phpbm flash
# the serial console
phpbm monitor
On a cloned project, run composer install before phpbm build. With "storage": "microsd", phpbm flash also copies the sources to the card; phpbm sync copies them again without rebuilding.
phpbm init writes the registry, conductor, the SDK and the board for you. The registry is listed with "canonical": true, so every php-baremetal/* package comes from here and never from Packagist. conductor is installed globally once so it is active while Composer resolves, and it stays in the project's require (with allow-plugins), not require-dev: without it, nothing binds the HALs.
{
"name": "acme/blink",
"type": "project",
"repositories": [
{
"type": "composer",
"url": "https://repository.php-baremetal.com",
"canonical": true
}
],
"require": {
"php-baremetal/conductor": "^1.0",
"php-baremetal/ext-sys": "^1.0",
"php-baremetal/ext-gpio": "^1.0"
},
"config": {
"allow-plugins": { "php-baremetal/conductor": true },
"platform": { "php": "8.5.11" }
},
"extra": {
"baremetal": {
"sdk": "esp32@^2.0",
"board": "waveshare-esp32-s3-zero-n8r8",
"runtime": "init-loop",
"storage": "embedded"
}
}
}
A package's role is its composer type. conductor installs every bm-* package in .phpbm/packages/; the SDK compiles them all into one ESP-IDF component.
A native PHP extension in C: the functions and classes you call. It declares its module (and a priority), requires the <x>-hal virtuals it needs and may declare registries for drivers.
ext-gpio · ext-i2cThe platform side of an extension: esp32-gpio-hal provides php-baremetal/gpio-hal over the ESP-IDF GPIO driver. It declares its platform and owns the chip build metadata: idf-requires, idf-dependencies, sdkconfig, partitions.
esp32-gpio-halShared C code, such as bm-common or esp32-executor, or a device driver, such as imu-qmi8658. A driver adds itself to an extension's registry with register.
bm-common · imu-qmi8658An extension of the PHP engine, php-baremetal/php-<name>. The package holds only php-ext; the SDK compiles the extension from PHP's own sources.
php-mbstring · php-pdo_sqliteAn extension never names a chip. Where it needs something chip-specific, it requires a virtual php-baremetal/<x>-hal: the slot. Each platform publishes a bm-hal that provides the slot and declares its platform in extra.baremetal.platform. Another SDK would only need its own HALs; the extensions and drivers stay the same.
Composer alone cannot choose a provider by platform, so conductor does it. The platform is the SDK name in extra.baremetal.sdk. Before the solve, conductor walks the requirements from the project down and, for every php-baremetal/<x>-hal it meets (even transitively), adds php-baremetal/<platform>-<x>-hal. Requiring ext-gpio in an esp32@^2.0 project therefore installs esp32-gpio-hal: you never name it.
{
"name": "php-baremetal/esp32-gpio-hal",
"type": "bm-hal",
"provide": { "php-baremetal/gpio-hal": "1.0.0" },
"extra": {
"baremetal": {
"platform": "esp32",
"idf-requires": ["esp_driver_gpio"]
}
}
}
This registry reads extra.baremetal.platform of every HAL to tell where a package builds. A HAL without it is shown as platform not declared and builds nowhere.
The project above requires ext-gpio and ext-sys (for delay()) and targets the esp32 SDK. Everything underneath follows.
ext-gpio # you required it (bm-ext, module gpio)
ext-sys # you required it (bm-ext, module sys)
esp32-gpio-hal # conductor added it (provides gpio-hal)
esp32-sys-hal # conductor added it (provides sys-hal)
esp32-executor # required by esp32-sys-hal (bm-lib)
void bm_gpio_hal_mode(int pin, int output);
void bm_gpio_hal_write(int pin, int level);
int bm_gpio_hal_read(int pin);
<?php
const LED = 2;
function setup(): void {
gpio_mode(LED, GPIO_OUTPUT);
}
function loop(int $tick): void {
gpio_write(LED, $tick % 2); // blink
delay(500);
}
The real dependency neighbourhood of php-baremetal/ext-gpio. Pick a platform to replace each slot with the HAL it resolves to.
Each slot is a virtual package; pick a platform to see the concrete build.
Each slot is replaced by its HAL; red means there is none yet.
requires HAL provides a slot driver registers into an extension slot with no HAL for this platform
A HAL (hardware abstraction layer) is the handful of chip calls one extension needs, behind neutral names. Every chip-specific extension has one: gpio-hal, i2c-hal, spi-hal, ledstrip-hal, events-hal, store-hal, sys-hal, wifi-hal, web-hal. The HAL also carries what the chip build needs: esp32-store-hal declares its own NVS partition, esp32-web-hal an sdkconfig fragment.
{
"platform": "esp32",
"idf-requires": ["nvs_flash"],
"partitions": [{ "name": "phpstore", "subtype": "nvs", "size": "24K" }]
}
A bus is an extension plus its HAL: ext-i2c gives you the Baremetal\I2c\Bus and Device classes, esp32-i2c-hal drives the chip's I2C peripheral. The extension also declares a registry, a C table named i2c_drivers. A device driver is a bm-lib that requires the extension and registers its descriptor into that table. The driver has no chip code, so it builds wherever ext-i2c does.
{ "module": "i2c", "registries": { "i2c_drivers": { "type": "i2c_driver_desc_t", "header": "i2c_driver_desc.h" } } }
{ "register": { "i2c_drivers": ["qmi8658_driver_desc"] } }
composer require php-baremetal/ext-i2c php-baremetal/imu-qmi8658
# extra.baremetal.sdk is "esp32@^2.0"
ext-i2c # Bus and Device, the i2c_drivers registry
imu-qmi8658 # the driver (you required it)
ext-events # required by ext-i2c
bm-common # shared C code, required by ext-i2c
esp32-i2c-hal # conductor added it (provides i2c-hal)
esp32-events-hal # conductor added it (provides events-hal)
esp32-executor # required by esp32-i2c-hal
#include <stddef.h>
#include "i2c_driver_desc.h"
extern const i2c_driver_desc_t qmi8658_driver_desc;
const i2c_driver_desc_t *const i2c_drivers[] = { &qmi8658_driver_desc, NULL };
const size_t i2c_drivers_count = 1;
In PHP you just talk to the device:
<?php
use Baremetal\I2c\Bus;
use Baremetal\I2c\Driver\Qmi8658;
$imu = new Qmi8658(new Bus(sda: 11, scl: 10));
[$ax, $ay, $az] = $imu->accel();
The real neighbourhood of php-baremetal/imu-qmi8658: the extension it registers into and the HALs underneath.
Each slot is a virtual package; pick a platform to see the concrete build.
Each slot is replaced by its HAL; red means there is none yet.
requires HAL provides a slot driver registers into an extension slot with no HAL for this platform
The firmware's PHP engine starts small. Extensions of PHP itself (mbstring, pdo_sqlite, opcache, zlib…) are switched on by requiring php-baremetal/php-<name>, a bm-php-ext package that holds only the extension's name. The SDK describes, for each PHP minor, how to compile it, what it requires (pdo_sqlite needs pdo), its options and what it costs in flash and RAM. The package pages here show that description, read from the SDK's latest release.
{
"name": "php-baremetal/php-mbstring",
"type": "bm-php-ext",
"extra": { "baremetal": { "php-ext": "mbstring" } }
}
"require": { "php-baremetal/php-mbstring": "^1.0" },
"extra": { "baremetal": {
"sdk": "esp32@^2.0",
"options": { "mbstring-cjk": false }
} }
A bm-php-ext works only with an SDK that ships that extension for your PHP minor; phpbm checks it before the build and says what is missing.
Both are defined by the SDK and picked in extra.baremetal.
| init-loop | runtime | Runs the script once, then setup() if it exists and loop($tick) forever, loop-interval ms apart. |
|---|---|---|
| event-driven | runtime | Needs ext-events. The script registers listeners and sources (timers, GPIO, network); events are then delivered from a queue. With ext-web, HTTP requests arrive as events. |
| web-server | runtime | Turns the network on and runs the entry script once per HTTP request, with no state shared between requests; static files are served directly. |
| embedded | storage | The sources are packed into a read-only partition of the flash and written with the firmware. |
| microsd | storage | The sources live on the board's microSD card; phpbm flash and phpbm sync copy them over the serial port. Needs a board with a card slot. |
A package builds on a platform when every <x>-hal it needs, directly or through its dependencies, has a published HAL for that platform. If one is missing, the registry names it: an invitation to publish it. Which boards a platform supports is up to its SDK: see the php-esp32-sdk board list.