Webová rozhraní API

Kromě samotného ECMAScriptu nabízí Phasis několik vrstev balíčků WHATWG / W3C API:

• Web Platform Pack — čisté hodnotové typy bez I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Fetch Pack — skutečný HTTP z JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, plná rozhraní WHATWG Streams (ReadableStream, WritableStream, TransformStream, strategie front, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw přes zlib; brotli, pokud je načteno rozšíření PECL kjdev/php-ext-brotli), navigator a globální alias podle specifikace HTML self + reportError.
• Crypto — crypto.getRandomValues, crypto.randomUUID a plné SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — včetně importu a exportu JWK. Založeno na ext-openssl.
• WebSocket — konstruktor, kodér/dekodér rámců RFC 6455, události. Výchozí přenosová vrstva používá stream_socket_client; lze ji nahradit pomocí Engine::setWebSocketTransport() pro ReactPHP / Ratchet / testovací mocky.
• XMLHttpRequest — postavené nad přenosovou vrstvou fetch, takže se uplatní stejné zásady i možnost výměny přenosové vrstvy.
• Smyčka událostí — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Také AsyncContext (Stage 3), které přenáší hodnoty přes hranice mikrotasků a časovačů.

Všechny balíčky jsou ve výchozím nastavení zapnuté. Bez příznaků a nastavování — typeof fetch vrací "function" v čerstvém new Engine().

Shoda se specifikací

Importovaný korpus Web Platform Tests (tests/Wpt/fixtures/) pokrývá AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, kompletní standard Streams (Readable/Writable/Transform + BYOB + fronty), structuredClone, URL / URLSearchParams, celé rozhraní crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — včetně tisíců kombinací derive-bits z hkdf a pbkdf2), stavový automat WebSocket (konstruktor URL a ověřování subprotokolů, sémantiku zavíracích kódů, send() pro řetězce / ArrayBuffer / pohledy na typovaná pole / Blob, binaryType, bufferedAmount, asynchronní zavření při připojování, možnost nastavit obslužné rutiny událostí na null) a širokou část Fetch + XMLHttpRequest — stavový automat responseType, přechody abort/send, hlavičky na seznamu CORS, nahrávání multipart FormData, XMLHttpRequestUpload + ProgressEvent, ověřování inicializace Response/Headers, statické konstruktory Response.json / Response.error, odstraňování Authorization v řetězci přesměrování, adresy blobů URL.createObjectURL, spotřebovávání těla přes body-mixin (text / blob / json / formData / arrayBuffer), Response.clone s rozdělenými proudy structuredClone-d a vyvolání síťové chyby u synchronního XHR. Všechny importované podtesty procházejí.

Pokrytí rozšíříte přidáním nového *.any.js do tests/Wpt/fixtures/<category>/ — runner ho automaticky načte. Sady testů XHR/Fetch řídí tests/Wpt/fetch-server.php (emulátor obslužných rutin WPT resources/*.py v jediném souboru); sada WebSocket používá nečinnou přenosovou vrstvu uvnitř runneru, která napodobuje otevření, echo a zavření, což stačí pro importované testovací případy. Korpus si můžete spustit sami:

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

Příklad 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();

Funguje to ihned po instalaci. Výchozí přenosová vrstva je PHP ext-curl. Těla proudí přes WHATWG ReadableStream, které Phasis poskytuje, takže funguje také for await (const chunk of res.body).

Příklad AbortController

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
  }
}

Implementováno je také AbortSignal.timeout(ms) (líná lhůta — kontrola při čtení aborted, místo vyvolání události uprostřed smyčky událostí; funguje u přenosových vrstev fetch, které během přenosu kontrolují signál).

Ovládací prvky embedderu (strana PHP)

Chování fetch řídí tři háčky na třídě Phasis\Engine:

$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);

Pokud se nezavolá setFetchTransport(), spustí se výchozí CurlTransport. Úložiště cookies je volitelné — žádné výchozí úložiště, žádné cookies se neukládají, dokud nějaké neposkytnete.

Příklad Streams

// 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

Plná specifikace Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, a navíc pipeTo / pipeThrough / tee.

Smyčka událostí

Globální objekt obsahuje setTimeout, setInterval, clearTimeout, clearInterval a queueMicrotask. Mikrotasky (obslužné rutiny Promise, queueMicrotask) se dokončí mezi každými makrotasky; časovače se spouštějí podle termínu prostřednictvím fronty pro danou oblast.

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

Zajišťuje ji Phasis's Engine::runEventLoop(), která po dokončení synchronního kódu automaticky volá eval() a evalAsModule(). Smyčka ve výchozím nastavení používá virtuální čas — setTimeout(cb, 5000) nečeká PHP; posune hodiny na termín, takže program rychle skončí. Embeddery s reálným časem řídí tickEventLoop() samy. Viz API: Smyčka událostí, kde najdete rozhraní na straně hostitele.

Co není součástí dodávky

Tato rozhraní API určená pouze pro prohlížeč nebo model běhového prostředí záměrně nespadají do rozsahu — podrobnosti najdete v části Známá omezení:

• window, document, strom DOM
• localStorage, sessionStorage, IndexedDB
• Worker, SharedWorker, MessageChannel
• Service Workers, Push API, Notifications, BroadcastChannel

Většinu z nich lze podle potřeby doplnit polyfillem přes $engine->setGlobal() na straně embedderu.

Rozšiřování korpusu WPT

tests/Wpt/upstream/ je řídká pokladna web-platform-tests/wpt zahrnující fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/ a dom/events/. Pokrytí rozšíříte tak, že zkopírujete libovolný soubor *.any.js z upstream/<area>/ do tests/Wpt/fixtures/<category>/. Runner ho při příštím spuštění načte; neúspěchy zaznamená přes bin/wpt --verbose.