php-baremetal/phpbm

Firmware Tools First-party

You're too curious come back at the end of November

The command-line tool that builds, flashes and monitors PHP firmware. It runs on your computer and drives an SDK, which knows the chip; Composer and the conductor plugin pick the packages.

phpbm turns a Composer project into firmware for a microcontroller. It runs on Linux, macOS or Windows, never on the board. phpbm itself knows nothing about a chip: an SDK (today esp32, from php-esp32-sdk) brings the boards, the PHP build recipe, the runtimes and the toolchain, and phpbm downloads, verifies and drives it.

How the pieces fit

Piece Role
Your project A composer.json with extra.baremetal (SDK, board, runtime, storage) and the PHP sources in project-src/.
Composer + conductor composer require picks the packages (extensions, drivers, PHP extensions). The php-baremetal/conductor plugin installs them into .phpbm/packages/, adds the HAL for the SDK's platform and writes .phpbm/manifest.json.
phpbm Reads the manifest, resolves and locks the SDK (phpbm.lock), checks the project against it, then builds, flashes, syncs and monitors.
SDK Describes the boards, chips, runtimes, storages and options, and carries the driver phpbm calls to build and flash.
Toolchain The SDK's compiler and flashing tools (ESP-IDF for esp32), installed by phpbm toolchain:install.

The packages come from the registry. phpbm, the conductor and the spec library they share are on Packagist; SDKs are GitHub releases listed in a release index.

Requirements

  • PHP 8.4 or later with the fileinfo extension (zip recommended), and Composer 2.
  • git, used to apply the SDK's patches to the PHP sources.
  • Whatever the SDK's toolchain needs. For esp32: Python 3.10 or later and about 6 GB of disk for ESP-IDF.
Warning Windows paths

ESP-IDF does not work from a path with spaces or non-ASCII characters. Keep your projects, and PHPBM_HOME if you move it, on a path without them.

Install

phpbm installs with Composer or as a single PHAR file. The conductor must be installed globally either way: it has to be active while Composer resolves a project for the first time.

Bash once per machine
composer global require php-baremetal/phpbm
composer global require php-baremetal/conductor
  • Composer: Composer's global vendor/bin must be on your PATH (composer global config bin-dir --absolute prints it).
  • PHAR: needs the same PHP, with the phar and zlib extensions (enabled in most PHP builds). Each release has phpbm.phar and SHA256SUMS; replace latest/download with download/v1.0.0 to pin a version, and download a new PHAR over the old one to update.

Where next

Documentation

Read the full documentation →
Last updated 2026-11-11 · v0.3.x Edit on GitHub Report issue