Skip to content
php-baremetal REGISTRY
Publish a package
Guide

How it works

A 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.

01The pieces

Each piece has one job, and each one lives in its own place.

composer.jsonthe project
The only source of truth. require lists the packages; extra.baremetal picks the SDK, the board, the runtime and the storage; config.platform.php is the PHP version.
conductorComposer plugin
A project dependency. It installs the bm-* packages in .phpbm/packages/, binds every php-baremetal/<x>-hal to the platform's implementation and writes .phpbm/manifest.json for phpbm.
phpbmthe CLI, installed once
It installs SDKs, scaffolds projects, validates them against the SDK, downloads and patches the PHP sources, then builds, flashes and monitors. It knows nothing about ESP-IDF: that is the SDK's job.
php-esp32-sdkthe SDK, on GitHub
It describes the chips (ESP32-S3, ESP32-P4), the boards, the runtimes, the storages and the optional PHP extensions, and compiles the firmware with ESP-IDF. Its name, esp32, is also the platform the HALs are bound to.
bm-* packagesthis registry
Native extensions, platform HALs, libraries and device drivers, and the switches for the SDK's PHP extensions. Each one describes its build in extra.baremetal, with no CMake of its own.
virtual slote.g. gpio-hal
Not a package of its own: a name like php-baremetal/gpio-hal that an extension requires and each platform fills with a bm-hal. The extension never names a chip.

02From composer.json to the board

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.json you write this composer install + conductor .phpbm/packages bm-* packages, HALs bound phpbm build php-esp32-sdk + ESP-IDF firmware phpbm flash board

Composer and conductor decide what goes in; phpbm and the SDK decide how it is built.

03Commands

bash once, on your computer
# 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
bash in your firmware project
# 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.

04The project is its composer.json

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.

json composer.json
{
  "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"
    }
  }
}
sdk
<name>@<constraint>. The name is also the platform conductor binds the HALs to; the exact version is pinned in phpbm.lock.
board
A board id of the SDK; the chip and the PSRAM come from the board. See the php-esp32-sdk board list.
runtime
init-loop, event-driven or web-server (below).
storage
embedded or microsd (below).
src, entry, env
The source folder and entry script (default project-src, index.php) and a .env file baked into the firmware.
board-overrides
Changes a peripheral of the board, such as {"microsd": {"cs": 5}}.
options
Typed options declared by the SDK, the runtime, the storage and the active PHP extensions, such as "on-error": "continue" or "mbstring-cjk": false. phpbm rejects an option nobody declares.

05Four package types

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.

bm-ext

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-i2c
bm-hal

Platform HAL

The 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-hal
bm-lib

Library or driver

Shared 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-qmi8658
bm-php-ext

PHP extension

An 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_sqlite

06Extensions, slots, platforms

An 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.

ext-gpio bm-ext require gpio-hal virtual slot provides provides esp32-gpio-hal bm-hal · platform esp32 <platform>-gpio-hal another SDK, same slot

07conductor binds the HALs

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.

json php-baremetal/esp32-gpio-hal: composer.json (excerpt)
{
  "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.

09How a HAL works

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.

PHP gpio_write(2, 1) ext-gpio module gpio gpio-hal mode / write / read the swappable layer esp32-gpio-hal over driver/gpio platform esp32
json php-baremetal/esp32-store-hal: extra.baremetal
{
  "platform": "esp32",
  "idf-requires": ["nvs_flash"],
  "partitions": [{ "name": "phpstore", "subtype": "nvs", "size": "24K" }]
}

10How a device driver works

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.

imu-qmi8658 bm-lib · device driver ext-i2c bm-ext · module i2c registry i2c_drivers require + register qmi8658_driver_desc require i2c-hal virtual slot esp32-i2c-hal bm-hal · platform esp32 provides conductor binds i2c-hal from "sdk": "esp32@^2.0"

1. The extension declares the registry, the driver fills it

json extra.baremetal of ext-i2c, then of imu-qmi8658
{ "module": "i2c", "registries": { "i2c_drivers": { "type": "i2c_driver_desc_t", "header": "i2c_driver_desc.h" } } }
{ "register": { "i2c_drivers": ["qmi8658_driver_desc"] } }

2. Require the bus and the driver

bash terminal
composer require php-baremetal/ext-i2c php-baremetal/imu-qmi8658
# extra.baremetal.sdk is "esp32@^2.0"
bash what conductor installs
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

3. The build generates the table

c phpbm_packages/registries.c (generated)
#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 project-src/index.php
<?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 live graph of imu-qmi8658

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

11PHP extensions come from the SDK

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.

json php-baremetal/php-mbstring (excerpt)
{
  "name": "php-baremetal/php-mbstring",
  "type": "bm-php-ext",
  "extra": { "baremetal": { "php-ext": "mbstring" } }
}
json your composer.json (excerpt)
"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.

12Runtimes and storage

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.

13Where things are published

This registry · canonical bm-* packages https://repository.php-baremetal.com, listed with "canonical": true
Packagist phpbm · conductor · spec phpbm also as a PHAR on its GitHub releases
GitHub Releases php-esp32-sdk The releases, installed by phpbm sdk:install esp32

14Will it build on my platform?

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.