Tīmekļa API

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 5b53f69

Papildus pašam ECMAScript, Phasis nodrošina vairākas WHATWG / W3C API pakotnes, kas veidotas slāņos:

Web Platform Pack — vērtību tipi bez I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
Fetch Pack — īsts HTTP no JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, pilns WHATWG Streams atbalsts (ReadableStream, WritableStream, TransformStream, rindas stratēģijas, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw, izmantojot zlib; brotli, ja ielādēts kjdev/php-ext-brotli PECL paplašinājums), navigator un globālais self alias atbilstoši HTML specifikācijai + reportError.
Crypto — crypto.getRandomValues, crypto.randomUUID un pilns SubtleCrypto atbalsts: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — kā arī JWK importēšana/eksportēšana. Darbību nodrošina ext-openssl.
WebSocket — konstruktors, RFC 6455 kadru kodētājs/dekodētājs, notikumi. Noklusētais transports izmanto stream_socket_client; to var aizstāt ar Engine::setWebSocketTransport(), lai testos izmantotu ReactPHP / Ratchet / imitācijas.
XMLHttpRequest — veidots virs fetch transporta, tāpēc darbojas tās pašas politiku āķu funkcijas un transportu var nomainīt.
Notikumu cikls — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Turklāt AsyncContext (3. stadija) pārnes vērtības pāri mikrouzdevumu / taimera robežām.

Visas pakotnes pēc noklusējuma ir ieslēgtas. Nav karogu vai iestatīšanas — typeof fetch jaunā new Engine() instancē atgriež "function".

Atbilstība

Importētajā Web Platform Tests testu kopā (tests/Wpt/fixtures/) ir ietverti AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, pilns Streams Standard (Readable/Writable/Transform + BYOB + rindas), structuredClone, URL / URLSearchParams, pilna crypto / SubtleCrypto saskarne (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — tostarp tūkstošiem derive-bits permutāciju no hkdf un pbkdf2), WebSocket stāvokļu automāts (konstruktora URL un apakšprotokola validācija, aizvēršanas koda semantika, send() virknēm / ArrayBuffer / tipizētu masīvu skatiem / Blob, binaryType, bufferedAmount, asinhrona aizvēršana savienojuma izveides laikā, notikumu apstrādātāja nullability) un plaša Fetch + XMLHttpRequest funkciju kopa — responseType stāvokļu automāts, abortēšanas/sūtīšanas pārejas, CORS atļauto galveņu saraksts, FormData augšupielādes ar vairākām daļām, XMLHttpRequestUpload + ProgressEvent, Response/Headers inicializācijas validācija, statiskie Response.json / Response.error konstruktori, Authorization galvenes noņemšana pēc novirzīšanas, URL.createObjectURL blob URL, pamatteksta jaukto metožu patērēšana (text / blob / json / formData / arrayBuffer), Response.clone ar structuredClone-d dublētām plūsmām un sinhrona XHR tīkla kļūdu izraisīšana. Visi importētie apakštesti tiek izturēti.

Lai papildinātu testu kopu, pievienojiet jaunu *.any.js vietnē tests/Wpt/fixtures/<category>/ — palaidējs to automātiski atradīs. XHR/Fetch testu kopas darbina tests/Wpt/fetch-server.php (viena faila WPT resources/*.py apstrādātāju emulators); WebSocket testu kopā tiek izmantots neaktīvs transporta modelis pašā palaidējā, kas imitē savienojuma atvēršanu, atbildes nosūtīšanu un aizvēršanu — ar to pietiek importētajiem testa datiem. Palaidiet testu kopu paši:

Apvalks

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

fetch() piemērs

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

Tas darbojas uzreiz. Noklusētais transports ir PHP ext-curl. Pamatteksta dati plūst caur WHATWG ReadableStream, ko nodrošina Phasis, tāpēc darbojas arī for await (const chunk of res.body).

AbortController piemērs

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

Ir ieviests arī AbortSignal.timeout(ms) (ar slinku termiņa pārbaudi — tā notiek aborted nolasīšanas laikā, nevis izsaucot notikumu notikumu cikla vidū; tas darbojas ar fetch transportiem, kas pārsūtīšanas laikā pārbauda signālu).

Iegultāja vadīklas (PHP puse)

Trīs āķa funkcijas Phasis\Engine klasē kontrolē fetch darbību:

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

Ja netiek izsaukts setFetchTransport(), darbojas noklusētais CurlTransport. Sīkdatņu krātuve ir jāieslēdz īpaši — pēc noklusējuma tās nav, un sīkdatnes netiek glabātas, ja vien to nenodrošināt.

Streams piemērs

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

Pilna Streams specifikācija: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, kā arī pipeTo / pipeThrough / tee.

Notikumu cikls

setTimeout, setInterval, clearTimeout, clearInterval un queueMicrotask atrodas globālajā objektā. Mikrouzdevumi (Promise apstrādātāji, queueMicrotask) tiek pilnībā izpildīti starp katru makrouzdevumu; taimeri nostrādā termiņa secībā, izmantojot katras vides rindu.

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

Tās darbību vada Phasis Engine::runEventLoop(), kas automātiski izsauc eval() un evalAsModule() pēc sinhronā koda izpildes. Pēc noklusējuma cikls izmanto virtuālo laiku — setTimeout(cb, 5000) neguļ PHP; cikls pavirza pulksteni līdz termiņam, lai programma ātri pabeigtos. Iegultāji, kuriem vajadzīgs reāllaiks, vada tickEventLoop() paši. Resursdatora saskarni skatiet API: Notikumu cikls.

Kas nav iekļauts

Tālāk minētie API, kas paredzēti tikai pārlūkprogrammām vai konkrētam izpildlaika modelim, apzināti nav iekļauti tvērumā — plašāku skaidrojumu skatiet sadaļā Zināmie ierobežojumi:

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

Ja nepieciešams, iegultājs lielāko daļu no tiem var aizstāt ar polifiliem, izmantojot $engine->setGlobal().

WPT testu kopas papildināšana

tests/Wpt/upstream/ ir web-platform-tests/wpt daļēja izrakstīšana, kas aptver fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/ un dom/events/. Lai paplašinātu pārklājumu, kopējiet jebkuru *.any.js failu no upstream/<area>/ uz tests/Wpt/fixtures/<category>/. Palaidējs to atradīs nākamajā palaišanas reizē; kļūdas tiek reģistrētas ar bin/wpt --verbose.