web-server
An HTTP server in the firmware that runs your entry script for every request, each time with a fresh PHP state, like PHP-FPM.
Set "runtime": "web-server" in extra.baremetal. The runtime requires the network capability: the board
needs a network type (see Network), and the network is switched on for you, without the
network option. Wired boards get an address by DHCP before PHP starts. On a Wi-Fi board the init script
connects with ext-wifi.
Lifecycle
-
Step 1: The init script runs (optional)
With the
initoption set, that script runs once, before the server starts, with the same time limit as a request. If it fails, the program ends. -
Step 2: The server starts
An HTTP server listens on
portand the console prints--- <entry> (web-server) http://<ip>:<port>/ ---. -
Step 3: Each request runs the entry script
A request starts a new PHP request, runs the entry script, sends what it printed, and shuts the request down. Nothing survives to the next request: no globals, no statics, no open resources.
The runtime never calls setup() or loop().
Options
| Option | Values | Default | Effect |
|---|---|---|---|
init |
A relative .php path, or empty |
empty | Script run once at boot, before the server starts, for example to connect to Wi-Fi. Relative to the source directory. If the file is missing the program stops with --- stopped: init script <path> not found ---. |
port |
1 to 65535 | 80 |
TCP port of the server. |
request-timeout |
0 to 3600 (s) | 30 |
Time limit for one request; see below. This SDK-wide option is read by this runtime. |
Requests and the time limit
The server takes one request at a time: while PHP runs a request, the next one waits, for at most
request-timeout plus 5 seconds.
- PHP gets
max_execution_timeequal torequest-timeout;0means no limit. - If PHP has not answered
request-timeoutplus 5 seconds after the request arrived, the client gets503 Service Unavailable, and the console printsphpbm: <method> <uri>: no answer within N s, 503 sent. PHP keeps running the request until it ends; its answer is dropped. - Until that request ends, every request that needs PHP gets
503 Service UnavailablewithRetry-After: 1at once (a request with a body also has its connection closed, so the body is not read). Static files are still served.
The server answers some requests without running PHP:
| Case | Answer |
|---|---|
A GET or HEAD for an existing file that is not a .php file, under the directory of the entry script |
The file, served directly, with a type taken from its extension |
A path with a .. segment, a backslash or a NUL after decoding |
404 Not Found |
| A header block larger than 2048 bytes | 431 Request Header Fields Too Large |
A body larger than post_max_size |
413 Content Too Large |
| A body that does not arrive in time (10 s plus 1 s per 16 KB) | 408 Request Timeout |
Every other path runs the entry script, so the script is also the router: read $_SERVER['REQUEST_URI'].
Methods GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS are served; HEAD runs like GET and
sends the headers and Content-Length without the body.
What PHP sees
| Input | Content |
|---|---|
$_SERVER |
REQUEST_METHOD, REQUEST_URI, QUERY_STRING, DOCUMENT_ROOT (the directory of the entry script), SERVER_PROTOCOL (HTTP/1.1), GATEWAY_INTERFACE, SERVER_NAME, SERVER_PORT, REMOTE_ADDR, REMOTE_PORT, SERVER_ADDR (when the board has an address), SERVER_SOFTWARE (phpbm), SCRIPT_FILENAME, SCRIPT_NAME, PHP_SELF, and the environment of the env file |
| Request headers | Only nine are passed: HTTP_HOST, HTTP_USER_AGENT, HTTP_ACCEPT, HTTP_ACCEPT_LANGUAGE, HTTP_COOKIE, HTTP_REFERER, HTTP_X_REQUESTED_WITH, HTTP_AUTHORIZATION and CONTENT_TYPE, each present only when the client sent it. Other headers are not available |
CONTENT_LENGTH |
Set when the request has a body |
$_GET, $_POST, $_COOKIE |
Filled by PHP from the query string, the body and the Cookie header |
php://input |
The raw request body |
The response is what the script prints. header(), http_response_code() and setcookie() work: the status
defaults to 200, and Content-Type defaults to text/html; charset=UTF-8. At most 48 response headers are
sent; a header past that limit is dropped with a console message.
Errors
on-error has no effect here. An error ends only the request that raised it, and the server keeps serving.
- A fatal error or an uncaught exception answers
500, and the console printsphpbm: <method> <uri>: <message>. Withdisplay_errorson (the firmware default) the error text is the body; otherwise the body isInternal Server Error. - An error the engine cannot recover inside the request also answers 500 and the server goes on.
exit()ends the request normally.- If the output does not fit in memory the answer is 500.
The program ends only when PHP can no longer start a request (the console prints
phpbm: web-server stopped: PHP cannot start a request), or when a request restarts the board with
sys_restart() or sys_deep_sleep(): that request is answered, later ones get 503, and the board restarts or
sleeps. Then restart-delay applies as in Runtimes.
Every request starts a fresh PHP state. With ext-events 1.0.2 and later, Events::listen(), dispatch() and
now() work inside a request and their listeners are dropped when it ends, while every(), watch_gpio(),
watch_button() and button_sampling() throw, in a request and in the init script. For timers, pin events, or HTTP with state kept between
requests, use ext-web in the event-driven runtime.
Example
08-network-web/web-server: the Waveshare ESP32-P4-ETH board serves its sources from the microSD card.
08-network-web/json-api routes on $_SERVER and reads a JSON body from php://input: