Package · Extension
Events and the reactor
Typed events, listeners and the sources that raise them (timer, pin edge, button), plus a lock that keeps the chip out of light sleep. The event-driven runtime requires it; conductor adds the events HAL for your platform.
ext-events lets a script react instead of running top to bottom. An event is an object of a class you
declare as a subclass of Baremetal\Event. Listeners are callables registered per event class with
Baremetal\Events::listen(). Sources raise events from below PHP: a periodic timer, a falling edge on a
pin, gestures on a push button. In the event-driven runtime the script runs once to register all of this,
then the runtime blocks on the event queue and delivers each event to its listeners on the PHP task, sleeping
in between.
The same queue carries events from other extensions: ext-i2c raises sample events from background
samplers, ext-web delivers HTTP requests and WebSocket frames. power_hold() and power_release() keep the
chip awake for a stretch when the power-save option is on.
Requirements
| Requires | Why |
|---|---|
php-baremetal/events-hal (virtual) |
The platform side: the event queue, periodic timers, GPIO interrupts, the light-sleep lock. On ESP32 it is php-baremetal/esp32-events-hal (platform esp32, over esp_timer, esp_driver_gpio and esp_pm). |
You never require the HAL yourself. Conductor reads the platform from extra.baremetal.sdk (esp32@^2.0
gives esp32) and adds php-baremetal/esp32-events-hal while Composer resolves. The PHP module is events;
it registers with priority 10, before other extensions, so Baremetal\Event exists when ext-i2c and
ext-web define their event classes.
The event-driven runtime declares ext-events as a required package: phpbm refuses to build an
event-driven project without it and tells you to run composer require php-baremetal/ext-events.
ext-i2c and ext-web require it too, so it also comes in with them.
Install
-
Install conductor once per machine
composer global require php-baremetal/conductorkeeps the plugin active during the first solve of a new project. -
Create the project
phpbm init my-eventswritescomposer.jsonwith conductor (^1.0, allowed as a plugin), the package registry, and the SDK, board, runtime and storage you pick. Pick theevent-drivenruntime. -
Require the extension
composer require php-baremetal/ext-events -
Build and flash
phpbm flashbuilds the firmware and flashes it;phpbm monitoropens the serial console.
The resulting composer.json, for a Waveshare ESP32-S3-Zero (N8R8), whose BOOT button is on GPIO0:
{
"name": "acme/my-events",
"type": "project",
"repositories": [
{ "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
],
"require": {
"php-baremetal/conductor": "^1.0",
"php-baremetal/ext-events": "^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": "event-driven",
"storage": "embedded"
}
}
}
A first script
project-src/index.php for the event-driven runtime: the top level registers listeners and starts
sources, then returns. From then on the runtime delivers events.
<?php
use Baremetal\Event;
use Baremetal\Events;
final class Tick extends Event {}
final class BootPressed extends Event {}
$ticks = 0;
Events::listen(Tick::class, function (Tick $e) use (&$ticks): void {
printf("tick %d\n", ++$ticks);
});
Events::listen(BootPressed::class, function (BootPressed $e): void {
echo "BOOT pressed\n";
});
every(1000, Tick::class); // timer source
watch_gpio(0, BootPressed::class); // GPIO0 falling edge, 200 ms debounce
echo "listeners and sources registered\n";
$ticks keeps its value between events: the script's variables stay alive for the whole run.
PHP API at a glance
| Name | Kind | Meaning |
|---|---|---|
Baremetal\Event |
class | Base class of every event. Properties: $device, the object that raised it or null; $time, readonly, when it was raised in nanoseconds (hrtime(true) base). |
Baremetal\TimerEvent |
class | Extends Event; every() fills public readonly int $ticks (1 plus the ticks coalesced into the event) when the class extends it ($ticks is filled per event class and coalesce value, so it is only meaningful for events raised by every(); another source raising the same class with the same coalesce value gets it too). |
Baremetal\PinEvent |
class | Extends Event; watch_gpio(), watch_gpios() and watch_button() fill public readonly int $pin and public readonly bool $level when the class extends it. |
Baremetal\Events::listen(string $event, callable $listener): void |
static method | Register a listener for one exact class. |
Baremetal\Events::now(Event $event): void |
static method | Deliver at once, on the caller's stack. |
Baremetal\Events::dispatch(Event $event): bool |
static method | Deliver breadth-first: events dispatched by listeners run after the current batch. false when no event slot is free or beyond 16 levels. |
Baremetal\Events::stats(): array |
static method | Slot pools, per-class counters (queued, delivered, dropped, coalesced) and cascade depths since boot. |
Baremetal\Source |
abstract class | The handle of a controllable source: stop(): void, start(): void, running(): bool (all final). Cannot be constructed, cloned or serialized. |
Baremetal\Timer |
final class | Extends Source; the handle every() returns: setPeriod(int|float $ms): void, period(): float. |
Baremetal\Button |
final class | Extends Source; the handle watch_button() returns: pin(): int. stop() pauses that button; a press held at start() is ignored until released. button_sampling() pauses all buttons. |
Baremetal\GpioWatch |
final class | Extends Source; the handle watch_gpio() and watch_gpios() return: pins(): array. stop() detaches the pins it still owns; the last watch of a pin owns it. |
every(int|float $ms, string $event, bool $coalesce = true): Baremetal\Timer |
function | Raise $event every $ms milliseconds (0.1 ms or more, rounded to the microsecond; every(1000 / 60, Frame::class) is 60 per second); a tick waits at most once. |
watch_gpio(int $pin, string $event, bool $coalesce = false): Baremetal\GpioWatch |
function | Raise $event on each falling edge of $pin, 200 ms debounce; returns the handle. |
watch_gpios(array $pins, string $event, bool $coalesce = false): Baremetal\GpioWatch |
function | Like watch_gpio() for several pins and one PinEvent class, debounced per pin. |
watch_button(int $pin, array $on, array $opts = []): Baremetal\Button |
function | Raise events for button gestures: pressed, released, held, click, repeat, double; returns the handle. |
button_sampling(bool $on): void |
function | Pause or resume the sampler of all buttons (a button stopped through its handle stays stopped). |
power_hold(): void, power_release(): void |
functions | Forbid or allow automatic light sleep. |
Failures throw \Exception with a readable message, invalid arguments \ValueError or \TypeError. See
Errors and limits.
Dependencies
- Requires the virtual
php-baremetal/events-hal, provided on ESP32 by esp32-events-hal. - Required by the
event-drivenruntime, by ext-i2c (sample events) and by ext-web (requests and frames as events).
Notes
- Sources only post to a queue. The
event-drivenruntime is what reads it: underinit-loopthe timers and interrupts run but their events are never delivered (the runtime gives their slots back after eachloop()).Events::now()andEvents::dispatch()work in every runtime. See Runtimes and delivery. - Listeners match the exact class: a listener on a parent class receives nothing from its subclasses.
- In
event-driventhe listener table is frozen when the top-level script returns;Events::listen()throws from then on. - Events raised by a source are created without calling their constructor.
- Events travel in slots allocated at boot: 64 small ones by default, shared by every source,
dispatch()and the other extensions, set with theevents-small,events-mediumandevents-largeoptions. A source event that finds no free slot is dropped and counted, and the first drop of a class prints a warning;Events::stats()andphpinfo()show the counters. At most 32 distinct event classes can be used by sources.
Related
- Events and listeners PHP API
- Sources PHP API
- Runtimes and delivery Reference
- esp32-events-hal HAL
- ext-web (HTTP as events) Extension
- ext-i2c (sensor events) Extension