Preskoči na vsebino

API-ji spleta

Prikaži kot Markdown Uredi na GitHub Dokumentacija za 5b53f69

Poleg samega ECMAScript Phasis ponuja več slojev API-jev WHATWG / W3C:

  • Paket spletne platforme — čisti tipi vrednosti, brez V/I: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Paket Fetch — dejanski HTTP iz JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, celoten WHATWG Streams (ReadableStream, WritableStream, TransformStream, strategije čakanja v vrsti, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw prek zlib; brotli, če je naložena razširitev PECL kjdev/php-ext-brotli), navigator ter globalni vzdevek self za specifikacijo HTML + reportError.
  • Kriptografija — crypto.getRandomValues, crypto.randomUUID in celoten SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — ter uvoz/izvoz JWK. Podpira ga ext-openssl.
  • WebSocket — konstruktor, kodirnik okvirjev RFC 6455 in dogodki. Privzeti prenos uporablja stream_socket_client; za ReactPHP / Ratchet / preizkusne ponaredke ga je mogoče zamenjati prek Engine::setWebSocketTransport().
  • XMLHttpRequest — zgrajen na prenosu fetch, zato veljajo isti kavlji pravilnikov in zamenljivi prenos.
  • Zanka dogodkov — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Poleg tega AsyncContext (stopnja 3) prenaša vrednosti prek meja mikroopravil / časovnikov.

Vsi paketi so privzeto vklopljeni. Brez zastavic in nastavitev — typeof fetch vrne "function" v svežem new Engine().

Skladnost

Uvoženi korpus Web Platform Tests (tests/Wpt/fixtures/) pokriva AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, celoten standard Streams (Readable/Writable/Transform + BYOB + čakalne vrste), structuredClone, URL / URLSearchParams, celoten nabor API-jev crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — vključno s tisoči kombinacij parametrov derive-bits iz hkdf in pbkdf2), stroj stanj WebSocket (konstruktor URL in preverjanje podprotokola, semantika kodov za zapiranje, send() za nize / ArrayBuffer / poglede na tipizirana polja / Blob, binaryType, bufferedAmount, asinhrono zapiranje med povezovanjem, možnost, da so obravnavalniki dogodkov null), ter širok nabor API-jev Fetch + XMLHttpRequest — responseType, prehode prekinitve/pošiljanja, glave na seznamu dovoljenih CORS, večdelne prenose FormData, XMLHttpRequestUpload + ProgressEvent, preverjanje začetnih nastavitev Response/Headers, statične konstruktorje Response.json / Response.error, odstranjevanje Authorization ob preusmeritvah, naslove blobov URL.createObjectURL, porabo telesa prek mešanice metod (text / blob / json / formData / arrayBuffer), Response.clone s tokovi, razdeljenimi prek structuredClone-d, in sinhrono proženje napake omrežja pri XHR. Vsi uvoženi podtesti so uspešni.

Če želite razširiti nabor, dodajte nov *.any.js v tests/Wpt/fixtures/<category>/ — zaganjalnik ga bo samodejno zaznal. Zbirkama XHR/Fetch pogon daje tests/Wpt/fetch-server.php (emulator v eni datoteki za obravnavalnike WPT resources/*.py); zbirka WebSocket uporablja neaktiven prenos znotraj zaganjalnika, ki posnema odpiranje/ping-pong/zapiranje in zadostuje za uvožene testne primere. Korpus zaženite sami:

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

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

To deluje takoj po namestitvi. Privzeti prenos je PHP ext-curl. Telesa se pretakajo prek standarda WHATWG ReadableStream, ki ga podpira Phasis, zato deluje tudi for await (const chunk of res.body).

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

Implementiran je tudi AbortSignal.timeout(ms) (leno preverjanje roka — preverja se ob branju aborted, namesto da bi se dogodek sprožil sredi zanke dogodkov; deluje pri prenosih fetch, ki med prenosom preverjajo signal).

Kontrole vdelovalnika (stran PHP)

Trije kavlji v razredu Phasis\Engine nadzorujejo vedenje 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);

Če funkcija setFetchTransport() ni poklicana, se zažene privzeta CurlTransport. Kozarec piškotkov je neobvezen — privzeto ga ni in piškotki se ne shranjujejo, razen če ga zagotovite sami.

Primer 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

Celotna specifikacija Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy ter pipeTo / pipeThrough / tee.

Zanka dogodkov

setTimeout, setInterval, clearTimeout, clearInterval in queueMicrotask so na globalnem objektu. Mikroopravila (obravnavalniki Promise, queueMicrotask) se v celoti izvedejo med vsakim makroopravilom; časovniki se prožijo po vrstnem redu rokov prek vrste, vezane na posamezno okolje.

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

Upravlja ga Phasis s svojo Engine::runEventLoop(), ki ju eval() in evalAsModule() samodejno pokličeta po koncu sinhrone kode. Privzeto uporablja virtualni čas — setTimeout(cb, 5000) ne povzroči dejanskega spanja, PHP; ura zanke se premakne do roka, zato se program hitro zaključi. Vdelovalniki v realnem času sami upravljajo tickEventLoop(). Za vmesnik na strani gostitelja glejte API: Zanka dogodkov.

Kaj ni vključeno

Ti API-ji, ki so na voljo samo v brskalnikih ali vezani na model izvajalnega okolja, so namenoma izven obsega — podrobnosti najdete v Znane omejitve:

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

Večino teh API-jev lahko po potrebi polifilira vdelovalnik prek $engine->setGlobal().

Razširjanje korpusa WPT

tests/Wpt/upstream/ je redek izrez web-platform-tests/wpt, ki pokriva fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Pokritost razširite tako, da katero koli datoteko *.any.js kopirate iz upstream/<area>/ v tests/Wpt/fixtures/<category>/. Zaganjalnik jo bo zaznal ob naslednjem zagonu; napake se zabeležijo prek bin/wpt --verbose.