ext-events

This package is part of php-baremetal.

What it is for

ext-events is the event loop seen from PHP. Your script declares events as classes, registers the listeners that handle them, and starts the sources that raise them; the firmware then sleeps until something happens and calls your listener.

It covers:

• events and listeners: Baremetal\Event, the base class of every event, and Baremetal\Events with listen(), now() and dispatch();
• sources: a periodic timer (every()), a pin edge (watch_gpio()), and a button with click, double-click, long-press and repeat (watch_button(), button_sampling());
• power: power_hold() and power_release() keep the chip awake for a stretch when automatic light sleep is on.

Other packages deliver through it as well: a sensor polled by ext-i2c, a request served by ext-web.

It needs an events HAL for your platform; on ESP32 that is php-baremetal/esp32-events-hal.

When to use it

It is core: every firmware requires it, whatever else the project uses. You work with it directly when your script has to react rather than run top to bottom: code that runs every N milliseconds, a button or a pin edge, a sensor that streams samples, an HTTP request, or a board that should sleep between events.

Install

composer require php-baremetal/ext-events php-baremetal/esp32-events-hal

Require the concrete HAL explicitly. Sources (every(), watch_gpio(), watch_button()) are delivered only in the event-driven execution model, set in composer.json:

{ "extra": { "baremetal": { "type": "event-driven" } } }

Example

The script runs once to register listeners and start sources; then the firmware sleeps until an event arrives and calls your listener.

<?php
use Baremetal\Event;
use Baremetal\Events;

final class Tick extends Event {}
final class Pressed extends Event {}

$n = 0;
Events::listen(Tick::class, function (Tick $e) use (&$n): void {
    printf("tick %d\n", ++$n);
});
Events::listen(Pressed::class, fn () => print("button\n"));

every(1000, Tick::class);          // a Tick every second
watch_gpio(0, Pressed::class);     // a Pressed on each falling edge of GPIO0

Documentation

• Overview: what it is, requirements, install, the API at a glance.
• PHP API: every class, method and function, with signatures and errors.
• How events are delivered: exact-class matching, now() vs dispatch(), the setup freeze, limits.
• Run code periodically: run code every N milliseconds.
• React to a button: click, double-click and long-press on one button.
• Power save while idle: sleep between events and stay awake only when needed.

Changelog

See CHANGELOG.md.

AI usage

AI is used as a tool here, on top of human engineering. The architecture, the design decisions and the hardware bring-up are done by hand. AI mostly helps with the documentation and with mechanical work that can be verified. The full policy, including what is expected of contributions made with AI, is in AI_USAGE.md.

Not for you? No worries at all. Nobody is forcing it on you, and a free, open-source project you didn't spend a minute or a cent on owes you no explanation anyway. Take it or leave it, no hard feelings.

And for everyone who's on board: when contributing, please follow the guidelines in AI_USAGE.md. Thanks!

License

MIT. See LICENSE.