Web-API's

Naast ECMAScript zelf levert Phasis verschillende gelaagde pakketten met WHATWG / W3C-API's:

• Web Platform Pack — pure waardetypen, geen I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Fetch Pack — echte HTTP van JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, volledige WHATWG Streams (ReadableStream, WritableStream, TransformStream, wachtrijstrategieën, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw via zlib; brotli wanneer de kjdev/php-ext-brotli PECL-extensie is geladen), navigator en de HTML-specificatiealias self + reportError.
• Crypto — crypto.getRandomValues, crypto.randomUUID en volledige SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — plus JWK-import/export. Aangedreven door ext-openssl.
• WebSocket — constructor, RFC 6455-framecodec, gebeurtenissen. Het standaardtransport gebruikt stream_socket_client; vervangbaar via Engine::setWebSocketTransport() voor ReactPHP / Ratchet / mocks in tests.
• XMLHttpRequest — gebouwd boven op het fetch-transport, dus dezelfde beleids-hooks en verwisselbare transportlaag zijn van toepassing.
• Event loop — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Plus AsyncContext (Stage 3), dat waarden doorgeeft over grenzen van microtasks / timers heen.

Alle pakketten zijn standaard ingeschakeld. Geen vlag, geen configuratie — typeof fetch retourneert "function" in een nieuwe new Engine().

Conformiteit

Het geïmporteerde corpus van Web Platform Tests (tests/Wpt/fixtures/) dekt AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, de volledige Streams Standard (Readable/Writable/Transform + BYOB + wachtrijen), structuredClone, URL / URLSearchParams, de volledige interface van crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — inclusief duizenden combinaties voor derive-bits van hkdf en pbkdf2), de statusmachine van WebSocket (constructor-URL en subprotocolvalidatie, semantiek van sluitcodes, send() voor strings / ArrayBuffer / getypeerde arrayweergaven / Blob, binaryType, bufferedAmount, asynchroon sluiten tijdens het verbinden, nullable event-handlers) en een brede selectie van Fetch + XMLHttpRequest — responseType-statusmachine, overgangen bij afbreken/verzenden, CORS-toegestane headers, multipart-uploads van FormData, XMLHttpRequestUpload + ProgressEvent, validatie van Response/Headers-initialisatie, de statische constructors Response.json / Response.error, het verwijderen van Authorization bij doorverwijzingen, URL.createObjectURL-blob-URL's, verwerking van body-mixins (text / blob / json / formData / arrayBuffer), Response.clone met structuredClone-d streams die worden gesplitst, en het gooien van netwerkfouten door synchrone XHR. Elke geïmporteerde subtest slaagt.

Om verder uit te breiden, plaats je een nieuw *.any.js in tests/Wpt/fixtures/<category>/ — de testrunner pikt het automatisch op. De XHR/Fetch-testsuites worden aangestuurd door tests/Wpt/fetch-server.php (een emulator in één bestand van de WPT-resources/*.py-handlers); de WebSocket-testsuite gebruikt een inerte transportlaag in de runner die open/echo/sluiten simuleert, voldoende voor de geïmporteerde testbestanden. Voer het corpus zelf uit:

bin/wpt                # everything
bin/wpt --category headers --verbose   # one area, per-subtest output
bin/wpt --json         # machine-readable

Voorbeeld met fetch()

const res = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "alice" }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const user = await res.json();

Dat werkt direct. Het standaardtransport is PHP ext-curl. Bodies worden gestreamd via de WHATWG ReadableStream die Phasis levert, dus for await (const chunk of res.body) werkt ook.

AbortController-voorbeeld

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 5000);
try {
  const res = await fetch(slowUrl, { signal: ctrl.signal });
} catch (e) {
  if (e.name === "AbortError") {
    // request was cancelled
  }
}

AbortSignal.timeout(ms) is ook geïmplementeerd (luie deadline — controleert bij aborted lezen in plaats van midden in de event loop een gebeurtenis af te vuren; werkt met fetch-transporten die het signaal tijdens de overdracht controleren).

Besturing voor embedder (PHP-zijde)

Drie hooks op de klasse Phasis\Engine bepalen het fetch-gedrag:

$engine = new Phasis\Engine();

// 1. Swap the HTTP transport. The callable receives a request descriptor
//    and an optional AbortSignal; returns a response descriptor.
$engine->setFetchTransport(function (array $request, $signal) {
    // ... use Guzzle, Symfony HttpClient, your stub, etc.
    return [
        'status' => 200,
        'statusText' => 'OK',
        'headers' => [['content-type', 'application/json']],
        'body' => '{"data":"value"}',
    ];
});

// 2. Pre-flight policy hook — rewrite, deny, or allow.
$engine->setFetchPolicy(function ($request) {
    $url = $request->get('url')->value;
    if (!str_starts_with($url, 'https://')) {
        throw new \RuntimeException('HTTPS only');
    }
    return null;  // allow as-is; return modified Request to rewrite
});

// 3. Cookie jar. Opt-in. Accepts any object with get(url):string and
//    set(url, header):void methods. JsObject or PHP object both work.
$engine->setCookieJar($myJar);

Als setFetchTransport() niet wordt aangeroepen, wordt de standaard-CurlTransport uitgevoerd. De cookiepot is opt-in — er is geen standaardcookiepot en er worden geen cookies opgeslagen tenzij je er een opgeeft.

Streams-voorbeeld

// Producer: ReadableStream that yields numbers 1..5
const rs = new ReadableStream({
  start(controller) {
    for (let i = 1; i <= 5; i++) controller.enqueue(i);
    controller.close();
  },
});

// Consumer: async iteration
for await (const value of rs) {
  console.log(value);  // 1, 2, 3, 4, 5
}

// Pipe through a transform
const ts = new TransformStream({
  transform(chunk, controller) { controller.enqueue(chunk * 2); },
});
const doubled = new ReadableStream({
  start(c) { [1, 2, 3].forEach(n => c.enqueue(n)); c.close(); }
}).pipeThrough(ts);
for await (const v of doubled) console.log(v);  // 2, 4, 6

Volledige Streams-specificatie: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, plus pipeTo / pipeThrough / tee.

Eventloop

setTimeout, setInterval, clearTimeout, clearInterval en queueMicrotask staan op het globale object. Microtasks (Promise-handlers, queueMicrotask) worden tussen elke macrotask volledig afgehandeld; timers worden in deadlinevolgorde geactiveerd via een wachtrij per realm.

console.log('sync');
queueMicrotask(() => console.log('microtask'));
setTimeout(() => console.log('timer'), 0);
// → sync, microtask, timer

const id = setInterval(() => console.log('tick'), 1000);
// ...later
clearInterval(id);

await new Promise(r => setTimeout(r, 50));   // common "delay" pattern works

Aangestuurd door de Engine::runEventLoop() van Phasis, die automatisch eval() en evalAsModule() aanroept nadat de synchrone code is afgelopen. De event loop gebruikt standaard virtuele tijd — setTimeout(cb, 5000) wacht niet PHP; de loop zet de klok vooruit naar de deadline zodat het programma snel klaar is. Embedders die echte tijd gebruiken, sturen tickEventLoop() zelf aan. Zie API: Event loop voor de host-interface.

Wat niet wordt meegeleverd

Deze API's die alleen in browsers bestaan of bij het runtime-model horen, vallen bewust buiten de scope — zie Bekende beperkingen voor de volledige uitleg:

• window, document, de DOM-boom
• localStorage, sessionStorage, IndexedDB
• Worker, SharedWorker, MessageChannel
• Service Workers, Push API, meldingen, BroadcastChannel

De meeste hiervan kunnen indien nodig door de embedder via $engine->setGlobal() worden geïmplementeerd als polyfill.

Het WPT-corpus uitbreiden

tests/Wpt/upstream/ is een sparse checkout van web-platform-tests/wpt voor fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Zo breid je de dekking uit: kopieer een willekeurig *.any.js-bestand van upstream/<area>/ naar tests/Wpt/fixtures/<category>/. De runner pikt het bij de volgende uitvoering op; fouten worden vastgelegd via bin/wpt --verbose.