Web-API:t

ECMAScriptin lisäksi Phasis sisältää useita WHATWG / W3C -rajapintapaketteja:

• Web Platform -paketti — puhtaita arvotyyppejä, ei I/O:ta: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Fetch-paketti — todellinen HTTP lähteestä JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, täydet WHATWG Streams -rajapinnat (ReadableStream, WritableStream, TransformStream, jonotusstrategiat, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw zlibin kautta; brotli, kun kjdev/php-ext-brotli PECL -laajennus on ladattu), navigator ja HTML-määrityksen mukainen self-yleisalias sekä reportError.
• Crypto — crypto.getRandomValues, crypto.randomUUID ja täysi SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — sekä JWK:n tuonti ja vienti. Pohjautuu ext-openssl:een.
• WebSocket — konstruktori, RFC 6455-kehyskooderi, tapahtumat. Oletussiirto käyttää stream_socket_client:tä; sen voi vaihtaa Engine::setWebSocketTransport()-koukulla ReactPHP-ympäristöä / Ratchet-ympäristöä / testeissä käytettäviä valekohteita varten.
• XMLHttpRequest — toteutettu fetch-siirron päälle, joten samat käytäntökoukut ja vaihdettava siirto ovat käytettävissä.
• Tapahtumasilmukka — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Lisäksi AsyncContext (Stage 3) välittää arvoja mikrotehtävä- ja ajastinrajojen yli.

Kaikki paketit ovat oletusarvoisesti käytössä. Ei lippuja eikä määrityksiä — typeof fetch palauttaa "function":n uudessa new Engine()-ympäristössä.

Vaatimustenmukaisuus

Tuotu Web Platform Tests -testikorpus (tests/Wpt/fixtures/) kattaa seuraavat osa-alueet: AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, Streams-standardin kaikki osat (Readable/Writable/Transform + BYOB + jonotus), structuredClone, URL / URLSearchParams, koko crypto / SubtleCrypto-rajapinta (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — mukaan lukien tuhannet derive-bits-yhdistelmät lähteistä hkdf ja pbkdf2), WebSocket-tilakone (konstruktori URL ja alikäytäntöjen validointi, sulkemiskoodien semantiikka, send() merkkijonoille / ArrayBuffer / tyypitetyille taulukkonäkymille / Blob, binaryType, bufferedAmount, asynkroninen sulkeminen yhdistettäessä, tapahtumankäsittelijöiden null-arvot) sekä laaja osa-alue Fetch- ja XMLHttpRequest-rajapinnoista — responseType-tilakone, keskeytys- ja lähetyssiirtymät, CORS-sallitut otsakkeet, multipart-FormData-lataukset, XMLHttpRequestUpload + ProgressEvent, Response/Headers-määrityksen validointi, staattiset Response.json / Response.error-konstruktorit, Authorization-otsakkeen poistaminen uudelleenohjausketjussa, URL.createObjectURL-blob-URL-osoitteet, runko-mixin käyttö (text / blob / json / formData / arrayBuffer), Response.clone ja structuredClone-osissa jaetut virrat sekä verkon virheen aiheuttava synkroninen XHR. Jokainen tuotu alitesti läpäistään.

Laajenna korpusta lisäämällä uusi *.any.js kohteeseen tests/Wpt/fixtures/<category>/ — suoritusohjelma löytää sen automaattisesti. XHR-/Fetch-testisarjoja ohjaa tests/Wpt/fetch-server.php (yhden tiedoston emulaattori WPT:n resources/*.py-käsittelijöille); WebSocket-testisarja käyttää suoritusohjelmaan sisältyvää passiivista siirtoa, joka synnyttää avaus-, kaiku- ja sulkemistapahtumat ja riittää tuoduille testitiedostoille. Suorita korpus itse:

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

fetch()-esimerkki

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

Se toimii suoraan. Oletusvastaanottaja on PHP ext-curl. Rungot virtaavat WHATWG:n ReadableStream Phasis-toimitusten kautta, joten myös for await (const chunk of res.body) toimii.

AbortController-esimerkki

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) on myös toteutettu (laiska määräajan tarkistus — tarkistus tehdään aborted-luvun yhteydessä tapahtuman laukaisemisen sijaan kesken tapahtumasilmukan; toimii fetch-siirroissa, jotka tarkistavat signaalin siirron aikana).

Upottajan säätimet (PHP-puoli)

Kolme koukkua luokassa Phasis\Engine ohjaavat fetch-toimintaa:

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

Jos setFetchTransport()-funktiota ei kutsuta, suoritetaan oletusarvoinen CurlTransport. Evästepurkki on valinnainen — oletuspurkkia ei ole eikä evästeitä tallenneta, ellet anna purkkia käyttöön.

Streams-esimerkki

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

Koko Streams-määritys: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy sekä pipeTo / pipeThrough / tee.

Tapahtumasilmukka

setTimeout, setInterval, clearTimeout, clearInterval ja queueMicrotask ovat yleisobjektissa. Mikrotehtävät (Promise-käsittelijät, queueMicrotask) suoritetaan loppuun jokaisen makrotehtävän välissä; ajastimet laukeavat määräaikajärjestyksessä ympäristökohtaisen jonon kautta.

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

Toiminta perustuu Phasis-olion Engine::runEventLoop()-ominaisuuteen, jonka eval() ja evalAsModule() kutsuvat automaattisesti synkronisen koodin suorituksen päätyttyä. Oletusarvoisesti silmukka käyttää virtuaaliaikaa — setTimeout(cb, 5000) ei nukuta PHP, vaan silmukka siirtää kellonsa määräaikaan, jolloin ohjelma valmistuu nopeasti. Reaaliaikaiset upottajat ajavat tickEventLoop()-toimintoa itse. Katso API: Tapahtumasilmukka isäntäpuolen rajapinnasta.

Mitä ei toimiteta

Nämä vain selaimissa tai tietyissä suoritusympäristömalleissa käytettävät rajapinnat on jätetty tarkoituksella soveltamisalan ulkopuolelle — katso koko keskustelu kohdasta Tunnetut rajoitukset:

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

Upottaja voi tarvittaessa toteuttaa useimmat näistä polyfilleillä $engine->setGlobal()-rajapinnan kautta.

WPT-testikorpuksen laajentaminen

tests/Wpt/upstream/ on kohteen web-platform-tests/wpt harva osakloonaus, joka kattaa fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/ ja dom/events/. Laajenna kattavuutta kopioimalla mikä tahansa *.any.js-tiedosto kohteesta upstream/<area>/ kohteeseen tests/Wpt/fixtures/<category>/. Suoritusohjelma löytää sen seuraavalla suorituskerralla; virheet kirjataan kohteen bin/wpt --verbose kautta.