Web API

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 5b53f69

Okrem samotného ECMAScriptu Phasis obsahuje niekoľko vrstvených balíkov API WHATWG / W3C:

Balík Web Platform — čisté typy hodnôt, bez V/V: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
Balík Fetch — skutočné HTTP z JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, plná podpora WHATWG Streams (ReadableStream, WritableStream, TransformStream, stratégie zaraďovania do frontu, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw cez zlib; brotli pri načítanom rozšírení PECL kjdev/php-ext-brotli), navigator a globálny alias self podľa špecifikácie HTML + 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 — plus import/export JWK. Založené na ext-openssl.
WebSocket — konštruktor, kodek rámcov RFC 6455, udalosti. Predvolený prenos používa stream_socket_client; možno ho vymeniť za Engine::setWebSocketTransport() pre ReactPHP / Ratchet / simulácie v testoch.
XMLHttpRequest — postavené na prenose Fetch, takže sa uplatňujú rovnaké háky pravidiel aj vymeniteľný prenos.
Slučka udalostí — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Navyše AsyncContext (Stage 3) prenáša hodnoty cez hranice mikrotaskov a časovačov.

Všetky balíky sú predvolene zapnuté. Bez príznakov a nastavovania — typeof fetch vráti "function" pri čerstvom new Engine().

Zhoda so štandardmi

Importovaný korpus Web Platform Tests (tests/Wpt/fixtures/) pokrýva AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, celý štandard Streams (Readable/Writable/Transform + BYOB + zaraďovanie do frontu), structuredClone, URL / URLSearchParams, celý rozsah crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — vrátane tisícok kombinácií parametrov derive-bits z hkdf a pbkdf2), stavový automat WebSocket (konštruktor URL a overovanie subprotokolu, sémantika zatváracích kódov, send() pre reťazce / ArrayBuffer / zobrazenia typovaných polí / Blob, binaryType, bufferedAmount, asynchrónne zatváranie počas pripájania, možnosť nastaviť obslužnú funkciu udalosti na null) a široký výber z Fetch + XMLHttpRequest — stavový automat responseType, prechody pri prerušení/odosielaní, hlavičky povolené v CORS, nahrávanie častí FormData, XMLHttpRequestUpload + ProgressEvent, overovanie inicializácie Response/Headers, statické konštruktory Response.json / Response.error, odstraňovanie Authorization pri presmerovaní, URL objektov URL.createObjectURL, spracovanie tiel pomocou body-mixin (text / blob / json / formData / arrayBuffer), Response.clone so streamami rozdelenými pomocou tee a označenými structuredClone-d a vyhadzovanie chyby siete pri synchronickom XHR. Každý importovaný podtest prechádza.

Ak chcete rozšíriť sadu, pridajte nové *.any.js do tests/Wpt/fixtures/<category>/ — runner ho zistí automaticky. Testovacie sady XHR/Fetch riadi tests/Wpt/fetch-server.php (jednosúborový emulátor obslužných funkcií resources/*.py WPT); sada WebSocket používa neaktívny prenos v runneri, ktorý simuluje otvorenie/echo/zatvorenie — to stačí pre importované testovacie prípady. Spustite korpus sami:

Shell

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

Príklad fetch()

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

Funguje to bez ďalšieho nastavovania. Predvolený prenos je PHP ext-curl. Telá sa prenášajú cez WHATWG ReadableStream, ktoré poskytuje Phasis, takže funguje aj for await (const chunk of res.body).

Príklad AbortController

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) je implementované tiež (oneskorenie sa kontroluje pri každom aborted čítaní, namiesto vyvolania udalosti uprostred slučky udalostí; funguje pri prenosoch fetch, ktoré počas prenosu kontrolujú signál).

Ovládanie z hostiteľskej strany (strana PHP)

Tri hooky v triede Phasis\Engine riadia správanie funkcie fetch:

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

Ak sa setFetchTransport() nezavolá, spustí sa predvolený CurlTransport. Zásobník súborov cookie je voliteľný — predvolene neexistuje a súbory cookie sa neukladajú, pokiaľ ho neposkytnete.

Príklad so Streams

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

Úplná špecifikácia Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, a tiež pipeTo / pipeThrough / tee.

Event loop

setTimeout, setInterval, clearTimeout, clearInterval a queueMicrotask sú na globálnom objekte. Mikrólohy (obslužné funkcie Promise, queueMicrotask) sa dokončia medzi každými makroúlohami; časovače sa spúšťajú podľa termínu prostredníctvom frontu pre jednotlivé kontexty.

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

Riadené Phasis Engine::runEventLoop(), ktoré eval() a evalAsModule() automaticky zavolajú po dokončení synchrónneho kódu. Slučka má predvolene virtuálny čas — setTimeout(cb, 5000) nespí PHP; posunie svoje hodiny na termín, takže sa program dokončí rýchlo. Vložené systémy v reálnom čase riadia tickEventLoop() samy. Pozrite si API: slučka udalostí, kde nájdete rozhranie na strane hostiteľa.

Čo sa nedodáva

Tieto rozhrania API určené len pre prehliadač alebo model prostredia sú zámerne mimo rozsahu — podrobnosti nájdete v časti Známe obmedzenia:

window, document, strom DOM
localStorage, sessionStorage, IndexedDB
Worker, SharedWorker, MessageChannel
Service Workers, Push API, oznámenia, BroadcastChannel

Väčšinu z nich môže podľa potreby doplniť hostiteľské prostredie pomocou $engine->setGlobal().

Rozširovanie korpusu WPT

tests/Wpt/upstream/ je čiastočná checkout kópia web-platform-tests/wpt pokrývajúca fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Ak chcete rozšíriť pokrytie, skopírujte ľubovoľný súbor *.any.js z upstream/<area>/ do tests/Wpt/fixtures/<category>/. Spúšťač ho pri ďalšom spustení zahrnie; zlyhania sa zaznamenajú cez bin/wpt --verbose.