Package · Extension
HTTP and WebSocket as events
HTTP requests and WebSocket frames delivered as events in the event-driven runtime: a listener returns a Response, state stays in PHP variables. Neutral extension; conductor adds the web HAL for your platform.
ext-web puts an HTTP server in front of an event-driven script. serve_http() starts it; each request is
read in full by the server task, then delivered to PHP as a Baremetal\Http\Request event. The first
listener that returns a Baremetal\Http\Response answers it. serve_ws() adds a WebSocket endpoint: each
inbound frame is a Baremetal\Http\Message event, and Message::reply() or ws_broadcast() send frames
back.
Requests share the reactor with every other event (timers, buttons, sensor samples), one at a time on the PHP
task. The script is never restarted between requests, so a counter, a cache or an open object keeps its
value. For a fresh PHP state per request, as with PHP-FPM, use the SDK's web-server runtime instead, which
needs no extension.
Requirements
| Requires | Why |
|---|---|
php-baremetal/web-hal (virtual) |
The HTTP server, its task and the hand-over of requests to the reactor. On ESP32 it is php-baremetal/esp32-web-hal (platform esp32, over esp_http_server). |
php-baremetal/ext-events |
The reactor queue, Events::listen(), and Baremetal\Event, which Request and Message extend. Its HAL (esp32-events-hal) is added the same way. |
You never require the HAL yourself. Conductor reads the platform from extra.baremetal.sdk (esp32@^2.0 gives
esp32) and adds php-baremetal/esp32-web-hal and php-baremetal/esp32-events-hal while Composer resolves.
The PHP module is web.
The project also needs:
- the
event-drivenruntime: only its reactor delivers requests; - a network interface when
serve_http()runs: on a wired board (Ethernet), the SDK option"network": "on"; on a Wi-Fi board,ext-wifiand awifi_connect()orwifi_ap_start()first.
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-webwritescomposer.jsonwith conductor, the package registry, and the SDK, board, runtime and storage you pick. Pick theevent-drivenruntime. -
Require the extension
composer require php-baremetal/ext-web, plusphp-baremetal/ext-wifion a Wi-Fi board. -
Build and flash
phpbm flashbuilds the firmware and flashes it;phpbm monitoropens the serial console.
The resulting composer.json for a Waveshare ESP32-S3-ETH, whose W5500 Ethernet the SDK brings up when the
network option is on:
{
"name": "acme/my-web",
"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",
"php-baremetal/ext-web": "^1.0"
},
"config": {
"allow-plugins": { "php-baremetal/conductor": true },
"platform": { "php": "8.5.11" }
},
"extra": {
"baremetal": {
"sdk": "esp32@^2.0",
"board": "waveshare-esp32-s3-eth",
"runtime": "event-driven",
"storage": "embedded",
"options": { "network": "on", "request-timeout": 10 }
}
}
}
ext-events would come in through ext-web anyway; the event-driven runtime asks for it by name.
A first script
<?php
use Baremetal\Events;
use Baremetal\Http\Request;
use Baremetal\Http\Response;
$hits = 0;
Events::listen(Request::class, function (Request $r) use (&$hits): Response {
$hits++;
return match (true) {
$r->method === 'GET' && $r->path === '/' => Response::html('<h1>php-baremetal</h1>'),
$r->method === 'GET' && $r->path === '/stats' => Response::json(['hits' => $hits]),
default => Response::notFound(),
};
});
serve_http(80);
echo "serving on http://", $_SERVER['SERVER_ADDR'] ?? 'the board', "/\n";
Routing is plain PHP (match, a router library): the extension has no router.
PHP API at a glance
| Name | Kind | Meaning |
|---|---|---|
serve_http(int $port = 80): bool |
function | Start the server; requests become Request events. |
serve_ws(string $path = '/ws'): bool |
function | Add a WebSocket endpoint; frames become Message events. |
ws_broadcast(string $data): int |
function | Queue a text frame to every connected WebSocket client. |
Baremetal\Http\Request |
class | An incoming request; extends Baremetal\Event. json(), header(). |
Baremetal\Http\Response |
class | The answer: status, body, content type, headers. Static helpers ok(), text(), html(), json(), notFound(), noContent(); header(). |
Baremetal\Http\Message |
class | An inbound WebSocket frame; extends Baremetal\Event. reply(). |
Startup failures throw \Exception, invalid arguments \ValueError. See
Errors and limits.
Dependencies
- Requires the virtual
php-baremetal/web-hal, provided on ESP32 by esp32-web-hal. - Requires ext-events for the reactor and the event base class.
- Works with ext-wifi on Wi-Fi boards, which provides the network interface.
Notes
- One request is handled at a time. While PHP handles one, the server task waits and serves nothing else, for
at most
request-timeout+ 5 s. Keep handlers short. - A handler runs with
max_execution_timeset to the SDK optionrequest-timeout(30 s by default). Going over it is a fatal error: the program stops, that request gets 500, and every request after it gets 503 until the board restarts. See Request lifecycle and timeouts. - An uncaught exception in a handler answers 500 and then follows
on-error: with the defaultstopthe program stops too. Set"on-error": "continue"to keep serving. $_GET,$_POST,$_REQUESTand$_SERVERare filled for each request;$_COOKIEand$_FILESare not.
Related
- HTTP PHP API
- Request lifecycle and timeouts Reference
- esp32-web-hal HAL
- ext-events Extension
- ext-wifi Extension