Hoppa till innehåll

Web API:er

Visa som Markdown Redigera på GitHub Dokumentation på 5b53f69

Utöver själva ECMAScript levererar Phasis flera lagerindelade paket med WHATWG- / W3C-API:er:

  • Web Platform-paketet — rena värdetyper utan I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Fetch-paketet — riktig HTTP från JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, fullständiga WHATWG Streams (ReadableStream, WritableStream, TransformStream, köstrategier, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw via zlib; brotli när PECL-tillägget kjdev/php-ext-brotli är laddat), navigator och det globala aliaset enligt HTML-specifikationen self + reportError.
  • Crypto — crypto.getRandomValues, crypto.randomUUID och fullständigt SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — samt import/export av JWK. Bygger på ext-openssl.
  • WebSocket — konstruktor, RFC 6455-ramkodning, händelser. Standardtransporten använder stream_socket_client och kan bytas ut via Engine::setWebSocketTransport() för ReactPHP / Ratchet / testmockar.
  • XMLHttpRequest — ligger ovanpå fetch-transporten, så samma policykrokar och utbytbara transport gäller.
  • Händelseloop — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Dessutom sprider AsyncContext (Stage 3) värden över gränser mellan mikrouppgifter och timers.

Alla paket är aktiverade som standard. Inga flaggor eller inställningar behövs — typeof fetch returnerar "function" på en ny new Engine().

Överensstämmelse

Den importerade korpusen med Web Platform Tests (tests/Wpt/fixtures/) omfattar AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, hela Streams Standard (Readable/Writable/Transform + BYOB + köhantering), structuredClone, URL / URLSearchParams, hela ytan för crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — inklusive tusentals permutationer för derive-bits från hkdf och pbkdf2), tillståndsmaskinen för WebSocket (konstruktor URL och validering av delprotokoll, semantik för stängningskoder, send() för strängar / ArrayBuffer / typade arrayvyer / Blob, binaryType, bufferedAmount, asynkron stängning under anslutning och nullbarhet för händelsehanterare) samt ett brett urval av Fetch + XMLHttpRequest — responseType-tillståndsmaskin, övergångar för avbrytning/sändning, rubriker på CORS-tillåtelselistan, multipart-överföringar med FormData, XMLHttpRequestUpload + ProgressEvent, validering av Response/Headers-initiering, de statiska konstruktorerna Response.json / Response.error, borttagning av Authorization vid omdirigeringskedjor, blob-URL:er för URL.createObjectURL, konsumtion av body-mixin (text / blob / json / formData / arrayBuffer), Response.clone med strömmar delade via structuredClone och synkront kastande av nätverksfel i XHR. Alla importerade deltester godkänns.

Lägg till en ny *.any.js i tests/Wpt/fixtures/<category>/ för att utöka testsviten — testköraren hittar den automatiskt. XHR-/Fetch-sviterna drivs av tests/Wpt/fetch-server.php (en emulator i en enda fil för WPT-hanterarna resources/*.py); WebSocket-sviten använder en inaktiv transport i testköraren som simulerar öppning, ekosvar och stängning, vilket räcker för de importerade testfixturerna. Kör testkorpusen själv:

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

fetch()-exempel

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

Det fungerar direkt. Standardtransporten är PHP ext-curl. Kroppar strömmas genom WHATWG ReadableStream som Phasis levererar, så for await (const chunk of res.body) fungerar också.

AbortController-exempel

JavaScript
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) är också implementerat (lazy-deadline — kontrolleras vid läsning av aborted i stället för att skicka en händelse mitt i händelseloopen; fungerar för fetch-transporter som avläser signalen under överföringen).

Styrning från inbäddaren (sidan PHP)

Tre krokar i klassen Phasis\Engine styr fetch-beteendet:

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

Om setFetchTransport() inte anropas körs standard-CurlTransport. Cookie-burken är opt-in — ingen standardburk och inga cookies lagras om du inte tillhandahåller en.

Streams-exempel

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

Hela Streams-specifikationen: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, samt pipeTo / pipeThrough / tee.

Händelseloop

setTimeout, setInterval, clearTimeout, clearInterval och queueMicrotask finns på det globala objektet. Mikrouppgifter (Promise-hanterare, queueMicrotask) körs klart mellan varje makrouppgift; timers utlöses i tidsfristordning via en kö per realm.

JavaScript
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

Drivs av Phasiss Engine::runEventLoop(), som eval() och evalAsModule() anropar automatiskt när den synkrona koden har körts klart. Loopen använder virtuell tid som standard — setTimeout(cb, 5000) väntar inte PHP; loopen flyttar fram klockan till tidsfristen så att programmet blir klart snabbt. Inbäddare som behöver realtid driver själva tickEventLoop(). Se API: Händelseloop för gränssnittet mot värdmiljön.

Det här ingår inte

Webbläsarspecifika API:er eller API:er från körningsmodellen ligger medvetet utanför omfånget — se Kända begränsningar för en fullständig genomgång:

  • window, document, DOM-trädet
  • localStorage, sessionStorage, IndexedDB
  • Worker, SharedWorker, MessageChannel
  • Service Workers, Push API, aviseringar, BroadcastChannel

De flesta av dessa kan vid behov polyfyllas av inbäddaren via $engine->setGlobal().

Utöka WPT-korpusen

tests/Wpt/upstream/ är en gles checkout av web-platform-tests/wpt som omfattar fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Så här utökar du täckningen: kopiera valfri *.any.js-fil från upstream/<area>/ till tests/Wpt/fixtures/<category>/. Testköraren hittar den nästa gång den körs; fel loggas via bin/wpt --verbose.