How it works
The U WebServer handles .php files through a transpile-compile-execute pipeline. There is no PHP interpreter in the loop — the server compiles PHP to native machine code through U as an intermediate language.
When a request arrives for a .php file, the server transpiles it to U, compiles the U to C via u2c, compiles the C to a shared library via gcc, and loads it with dlopen. The compiled .so is cached by source mtime — subsequent requests execute the cached binary directly. Source changes trigger automatic recompilation.
The Pipeline
Four stages, fully automatic. The first request compiles; every request after that runs native code.
The transpiler is available in two implementations: a JS version (transpilers/php-to-u.js, 3,104 lines) and a Python fallback (tools/php2u.py). The server auto-detects which is available and prefers the JS version when node is on the path.
The PHP Transpiler
A source-to-source compiler that translates PHP syntax to U. Handles classes, closures, type annotations, ternaries, array destructuring, and PHP's implicit type coercions.
Superglobal rewriting
PHP's $_GET, $_POST, $_SERVER, $_SESSION, $_COOKIE are rewritten to sapi.get, sapi.post, etc. — explicit parameters instead of mutable globals, so the server can handle multiple requests in one process.
Function mapping
PHP builtins map to U stdlib: strlen → .len, json_encode → JSON.encode, array_map → .map. Functions without a stdlib equivalent call into PhpCompat, which implements the exact PHP behaviour.
Truthiness guards
PHP's loose truthiness (0, "", [] are falsy) differs from U's type-strict booleans. The transpiler wraps conditions in _ensureBool() to preserve PHP semantics in conditional and loop guards.
Nullable inference
The transpiler tracks which variables may hold null and adds U's +N modifier. Nullable access uses ?. (safe navigation) or guard blocks to match PHP's implicit null handling.
Mutability tracking
PHP variables are mutable by default; U variables are immutable. The transpiler detects reassignment and adds +M modifiers to variables that are written after their initial binding.
PSR-4 autoloading
PHP's use and namespace declarations are resolved to U's o imports. PSR-4 class autoloading is mapped to static imports at transpile time — no runtime class loader needed.
The SAPI Layer
PhpSAPI provides the per-request context that PHP code expects: headers, output buffering, sessions, cookies — without mutable global state.
This explicit-SAPI design is what makes it possible for the U WebServer to handle multiple PHP requests in one process without forking. Each request gets its own PhpSAPI instance — no shared mutable state, no globals, no request leakage.
PhpCompat Library
1,194 functions across 10,992 lines that reproduce PHP's standard library in native U. Not shims or stubs — real implementations with PHP-correct semantics.
The PhpCompat module is organized by category. Each function implements the exact PHP behaviour: array_merge renumbers integer keys, substr accepts negative offsets, sprintf handles all format specifiers.
Migration Path: PHP → U
You don't have to migrate all at once. The U WebServer runs .php and .u files side by side, so you can convert endpoints one at a time.
| Approach | What changes | Binary size | Effort |
|---|---|---|---|
| Keep PHP | Nothing. Drop files in, server transpiles them. | Includes PhpCompat + PhpSAPI | Zero |
| Mixed .php + .u | New endpoints in U, old ones stay PHP. | Mixed | Incremental |
| Pure .u | All handlers are native U. No PHP layer. | Smallest (tree-shaken) | Full rewrite |
A native .u handler is simpler than a PHP file because it doesn't need the SAPI layer. It receives an HttpReq and returns an HttpResp directly:
The .u version compiles with -ffunction-sections -fdata-sections and links with --gc-sections, so the resulting shared library contains only the stdlib functions the handler actually calls. A hello-world handler compiles to a few KB.
Framework Support
The transpiler handles real-world PHP patterns: classes with inheritance, traits, interfaces, closures, type annotations, and exception handling.
Qbix Platform
The U WebServer was built to run the Qbix Platform. The PhpCompat library covers Qbix's use of PHP's standard library: sessions, PDO, cURL, image processing (GD), cryptography (sodium/openssl), and the full string/array/math surface. The transpiler handles Qbix's namespace conventions and autoloading.
Laravel / Symfony patterns
PSR-4 autoloading is resolved at transpile time. Namespace declarations and use statements are converted to U's o (import) directives. Type-hinted dependency injection parameters are translated to U struct fields. Laravel-style closures (Route::get('/path', function () { ... })) are translated to U lambdas.
WordPress / procedural PHP
Procedural PHP with global function calls and superglobals is the simplest case for the transpiler. Function-level PHP (add_filter, add_action) maps directly. The main challenge is dynamic include/require with computed paths, which requires the full file set to be known at transpile time.
Performance
Transpiled PHP runs as native code. After the first-request compilation, there is no interpreter, no opcode cache, no JIT warmup — just compiled C.
First request: compile
The first request to a PHP file triggers transpilation + compilation. This takes a few seconds depending on file size. The compiled .so is cached on disk.
Subsequent requests: native
After compilation, the server calls the handler through a function pointer — dlsym to find it, then a direct call. No interpreter overhead, no opcode decoding, no garbage collector pauses.
Smart caching
The PhpCache module tracks source mtime. Edit a PHP file and the next request recompiles it automatically. Unchanged files keep using the cached binary indefinitely.
| Metric | PHP-FPM | U WebServer (transpiled PHP) |
|---|---|---|
| Startup | PHP interpreter + OPcache warmup | Native binary, instant |
| Execution | Zend VM bytecode interpretation | Compiled native code |
| Memory | PHP runtime per-worker | Shared binary, no interpreter |
| Concurrency | One process per request (FPM) | Event loop, shared process |
| First request | Immediate (interpreted) | Compile delay (cached after) |