Package · Extension
Wi-Fi from PHP
Scan, join a network or open an access point from PHP. The firmware never connects by itself and keeps no credentials in its configuration. Neutral extension; conductor adds the Wi-Fi HAL for your platform.
ext-wifi gives the script control of the board's Wi-Fi radio. As a station it scans for networks and
joins one, waiting until it has an IP address. As an access point it opens the board's own network, with
a DHCP server, so a phone or laptop can join it directly. Both roles can run at the same time. In the
event-driven runtime it also raises events for what happens on the radio: the station connects, drops or
gives up, a scan ends, a station joins the access point.
The SDK brings up the TCP/IP stack and the event loop on every board, but on a Wi-Fi board it never joins a
network and never reads credentials: connecting is always a call in your script. Once connected, whatever
uses the network works over it, ext-web included.
Requirements
| Requires | Why |
|---|---|
php-baremetal/wifi-hal (virtual) ^1.1 |
The radio driver lifecycle: init, scan, station, access point, and the driver events. On ESP32 it is php-baremetal/esp32-wifi-hal (platform esp32, over esp_wifi, esp_netif, esp_event, nvs_flash), which also brings php-baremetal/esp32-executor. |
php-baremetal/ext-events ^1.1 |
The event bus the Wi-Fi events travel on (wifi_events()). |
php-baremetal/events-hal (virtual) ^1.3 |
The lock that guards the station state, which the driver events update from their own task. On ESP32 it is php-baremetal/esp32-events-hal, already brought by ext-events. |
You never require the HAL yourself. Conductor reads the platform from extra.baremetal.sdk (esp32@^2.0 gives
esp32) and adds php-baremetal/esp32-wifi-hal while Composer resolves. The PHP module is wifi. Since
ext-wifi 1.1.0 it requires ext-events, which Composer installs with it. The functions work in every runtime;
the events are delivered in the event-driven runtime (in init-loop nothing delivers them, and
wifi_events() throws in web-server).
Boards
The SDK checks the board when it builds:
| Board network | ext-wifi |
|---|---|
wifi (ESP32-S3 boards such as the Waveshare ESP32-S3-Zero, the ESP32-S3-DevKitC-1, the Waveshare ESP32-S3-Touch-LCD-1.85B) |
Required to get any network. "network": "on" without ext-wifi is a build error: board '...' connects over Wi-Fi from PHP: composer require php-baremetal/ext-wifi. |
wifi-c6 (Waveshare ESP32-P4-WIFI6: an ESP32-C6 companion over ESP-Hosted) |
Same as wifi; the companion link is started at boot. Builds, not yet verified on hardware. |
| Wired network on a chip with a radio (Waveshare ESP32-S3-ETH) | Optional; Wi-Fi then runs next to Ethernet. |
| No radio (Waveshare ESP32-P4-ETH, Waveshare ESP32-P4-Pico, generic ESP32-P4) | Build error: board '...' has no Wi-Fi: remove php-baremetal/ext-wifi. |
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-wifiwritescomposer.jsonwith conductor, the package registry, and the SDK, board, runtime and storage you pick. -
Require the extension
composer require php-baremetal/ext-wifi -
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), with the credentials in a .env file that
is baked into the firmware and kept out of the sources and of git:
{
"name": "acme/my-wifi",
"type": "project",
"repositories": [
{ "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
],
"require": {
"php-baremetal/conductor": "^1.0",
"php-baremetal/ext-wifi": "^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",
"env": ".env"
}
}
}
WIFI_SSID=my-network
WIFI_PASSWORD=my-password
A first script
<?php
function setup(): void
{
$ssid = getenv('WIFI_SSID') ?: '';
$pass = getenv('WIFI_PASSWORD') ?: null;
echo "connecting to '$ssid'...\n";
if (wifi_connect($ssid, $pass)) {
printf("connected: %s (%d dBm)\n", wifi_ip(), wifi_rssi());
} else {
echo "connect failed\n";
}
}
function loop(int $tick): void
{
echo wifi_connected() ? "online " . wifi_ip() . "\n" : "offline\n";
usleep(5000000);
}
PHP API at a glance
| Function | Returns | Meaning |
|---|---|---|
wifi_scan(bool $wait = true) |
array or false; bool with wait: false |
Networks in range: ssid, bssid, rssi, channel, auth; or start a scan and return. |
wifi_connect(string $ssid, ?string $password = null, int $timeout_ms = 30000, bool $wait = true, int $retries = 10, PowerSave $power_save = PowerSave::Minimum) |
bool |
Join a network and wait for an IP address, or start joining and return; $power_save sets how much the radio sleeps while connected. |
wifi_disconnect() |
bool |
Leave the network. |
wifi_connected() |
bool |
Whether the station has an IP address. |
wifi_state(), wifi_ssid() |
Baremetal\Wifi\State, ?string |
Station state (Idle, Connecting, Connected, Online) and the network asked for or in use. |
wifi_ip(), wifi_rssi() |
?string, ?int |
Station address and signal, null when not connected. |
wifi_ap_start(string $ssid, ?string $password = null, int $channel = 1, int $max_conn = 4) |
bool |
Open the board's own network. |
wifi_ap_stop() |
bool |
Close it. |
wifi_ap_ip(), wifi_ap_clients() |
?string, int |
Access point address and number of joined stations. |
wifi_ap_active() |
bool |
Whether the access point is up. |
wifi_events() |
Baremetal\Wifi\Events |
Turn on the Wi-Fi events. |
wifi_available() |
bool |
Whether the radio comes up. |
No function throws for a Wi-Fi failure: each reports it in its return value (and, with the events, in
ConnectFailed::$reason or Disconnected::$reason).
Dependencies
- Requires the virtual
php-baremetal/wifi-hal, provided on ESP32 by esp32-wifi-hal, which runs every driver call on esp32-executor. - Requires ext-events for its events.
- Gives ext-web its network interface on Wi-Fi boards.
Notes
wifi_scan()andwifi_connect()block the script while they wait (up to 15 s for a scan,$timeout_msfor a connect). In theevent-drivenruntime nothing else is delivered meanwhile: there, usewait: falseand the events.- With the
web-serverruntime on a Wi-Fi board, connect in theinitscript (the runtime optioninit), which runs once before the server starts. - The first Wi-Fi call initialises the radio and the
nvsflash partition. See How it runs for what that means for stored settings.
Related
- Station PHP API
- Access point PHP API
- Events PHP API
- How it runs Reference
- esp32-wifi-hal HAL
- ext-web Extension