Webes API-k

Magán az ECMAScripten túl a Phasis a WHATWG / W3C API-k több rétegét is biztosítja:

• Web Platform Pack — tiszta értéktípusok, I/O nélkül: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Fetch Pack — valódi HTTP a JavaScript felől: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, teljes WHATWG Streams (ReadableStream, WritableStream, TransformStream, sorbaállítási stratégiák, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw a zlib segítségével; brotli, ha be van töltve a kjdev/php-ext-brotli PECL-bővítmény), navigator és a HTML-specifikációjú self globális alias + reportError.
• Crypto — crypto.getRandomValues, crypto.randomUUID és teljes SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — valamint JWK-import/export. Alapja a ext-openssl.
• WebSocket — konstruktor, RFC 6455 keretkódoló/-dekódoló, események. Az alapértelmezett transzport a stream_socket_client; a Engine::setWebSocketTransport() segítségével lecserélhető ReactPHP / Ratchet / tesztbeli mockok használatára.
• XMLHttpRequest — a fetch-transzportra épül, így ugyanazok a házirend-hookok és a cserélhető transzport is érvényesek.
• Eseményhurok — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Továbbá AsyncContext (Stage 3), amely mikrotaszk- és időzítőhatárokon át továbbítja az értékeket.

Minden csomag alapértelmezés szerint be van kapcsolva. Nincs kapcsoló vagy beállítás — a typeof fetch egy friss new Engine() példányon "function" értéket ad vissza.

Megfelelőség

Az importált Web Platform Tests tesztkorpusz (tests/Wpt/fixtures/) lefedi a következőket: AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, a teljes Streams Standard (Readable/Writable/Transform + BYOB + sorbaállítás), structuredClone, URL / URLSearchParams, a teljes crypto / SubtleCrypto felület (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — több ezer bitszármaztatási kombinációval, többek között a hkdf és pbkdf2 alapján), a WebSocket állapotgépe (konstruktor-URL és alprotokoll-ellenőrzés, zárókódok szemantikája, send() karakterláncokhoz / ArrayBuffer / típusos tömbnézetekhez / Blob, binaryType, bufferedAmount, aszinkron lezárás csatlakozás közben, eseménykezelők nullázhatósága), valamint a Fetch + XMLHttpRequest széles körű részét — responseType állapotgép, megszakítási/küldési átmenetek, CORS által engedélyezett fejlécek, többrészes FormData-feltöltések, XMLHttpRequestUpload + ProgressEvent, Response/Headers inicializálásának ellenőrzése, statikus Response.json / Response.error konstruktorok, Authorization fejlécek eltávolítása az átirányítási láncban, URL.createObjectURL blob-URL-ek, a törzs-mixin feldolgozása (text / blob / json / formData / arrayBuffer), Response.clone structuredClone-d felosztott adatfolyamokkal, valamint szinkron XHR esetén a hálózati hibák kiváltása. Minden importált részteszt sikeres.

A bővítéshez helyezzen el egy új *.any.js elemet a tests/Wpt/fixtures/<category>/ mappában — a futtató automatikusan felismeri. Az XHR/Fetch tesztcsomagokat a tests/Wpt/fetch-server.php vezérli (a WPT resources/*.py kezelőinek egyfájlos emulátora); a WebSocket tesztcsomagja egy futtatóba épített, nem aktív transzportot használ, amely open/echo/close eseményeket állít elő, és elegendő az importált tesztadatokhoz. Futtassa le Ön is a korpuszt:

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

fetch()-példa

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

Ez azonnal működik. Az alapértelmezett transzport: PHP ext-curl. A törzsek a WHATWG ReadableStream adatfolyamon keresztül továbbítódnak, amelyet a Phasis biztosít, így a for await (const chunk of res.body) is működik.

AbortController-példa

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

A AbortSignal.timeout(ms) is meg van valósítva (lusta határidő-ellenőrzés — aborted olvasáskor ellenőriz, nem vált ki eseményt az eseményhurok közepén; olyan fetch-transzportoknál működik, amelyek az átvitel során lekérdezik a jelet).

Beágyazó vezérlők (PHP oldala)

A Phasis\Engine osztály három hookja szabályozza a fetch működését:

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

Ha nem hívja meg a setFetchTransport() függvényt, akkor az alapértelmezett CurlTransport fut le. A sütitároló csak külön bekapcsolva használatos — alapértelmezés szerint nincs tároló, és nem tárolódnak sütik, hacsak nem ad meg egyet.

Streams-példa

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

A Streams specifikáció teljes támogatása: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, valamint pipeTo / pipeThrough / tee.

Eseményhurok

A globális objektumon érhető el: setTimeout, setInterval, clearTimeout, clearInterval és queueMicrotask. A mikrotaszkok (Promise-kezelők, queueMicrotask) minden makrotaszk között teljesen lefutnak; az időzítők a határidők sorrendjében, realmenkénti soron keresztül aktiválódnak.

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

A vezérlést a Phasis Engine::runEventLoop() végzi, amely automatikusan meghívja a eval() és evalAsModule() függvényeket a szinkron kód befejeződése után. Alapértelmezés szerint az eseményhurok virtuális időt használ — a setTimeout(cb, 5000) nem vár PHP; az óra a határidőig előreugrik, így a program gyorsan befejeződik. A valós idejű beágyazók maguk működtetik a tickEventLoop() elemet. A gazdagépi felületről lásd: API: Eseményhurok.

Mi nincs benne

Ezek a kizárólag böngészőben elérhető vagy futtatókörnyezet-modellhez tartozó API-k szándékosan kívül esnek a hatókörön — a teljes leírást lásd az Ismert korlátozások oldalon:

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

Szükség esetén ezek többsége a beágyazó által, $engine->setGlobal() segítségével polifillelhető.

A WPT tesztkorpusz bővítése

A tests/Wpt/upstream/ a web-platform-tests/wpt ritkított letöltése, amely ezeket fedi le: fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. A lefedettség bővítéséhez másolja át a upstream/<area>/ bármelyik *.any.js fájlját a tests/Wpt/fixtures/<category>/ mappába. A futtató a következő futáskor automatikusan felismeri; a hibákat a bin/wpt --verbose naplózza.