Lewati ke konten

API Web

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 5b53f69

Selain ECMAScript itu sendiri, Phasis menyertakan beberapa paket API WHATWG / W3C berlapis:

  • Paket Web Platform — tipe nilai murni, tanpa I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Paket Fetch — HTTP nyata dari JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, WHATWG Streams lengkap (ReadableStream, WritableStream, TransformStream, strategi antrean, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw melalui zlib; brotli saat ekstensi PECL kjdev/php-ext-brotli dimuat), navigator, serta alias global self sesuai spesifikasi HTML + reportError.
  • Kripto — crypto.getRandomValues, crypto.randomUUID, dan SubtleCrypto lengkap: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — serta impor/ekspor JWK. Didukung oleh ext-openssl.
  • WebSocket — konstruktor, codec frame RFC 6455, peristiwa. Transportasi bawaan menggunakan stream_socket_client; dapat diganti melalui Engine::setWebSocketTransport() untuk ReactPHP / Ratchet / mock dalam pengujian.
  • XMLHttpRequest — dibangun di atas transportasi fetch, sehingga hook kebijakan dan transportasi yang dapat diganti tetap berlaku.
  • Event loop — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Ditambah AsyncContext (Tahap 3) yang meneruskan nilai melintasi batas microtask / timer.

Semua paket aktif secara default. Tanpa flag, tanpa penyiapan — typeof fetch mengembalikan "function" pada new Engine() baru.

Kesesuaian

Kumpulan Web Platform Tests yang diimpor (tests/Wpt/fixtures/) mencakup AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, Streams Standard lengkap (Readable/Writable/Transform + BYOB + antrean), structuredClone, URL / URLSearchParams, seluruh permukaan crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — termasuk ribuan variasi derive-bits dari hkdf dan pbkdf2), mesin status WebSocket (konstruktor URL dan validasi subprotokol, semantik kode penutupan, send() untuk string / ArrayBuffer / tampilan typed-array / Blob, binaryType, bufferedAmount, penutupan asinkron saat menghubungkan, nullable pengendali peristiwa), serta cakupan luas Fetch + XMLHttpRequest — mesin status responseType, transisi abort/send, header yang diizinkan CORS, unggahan multipart FormData, XMLHttpRequestUpload + ProgressEvent, validasi init Response/Headers, konstruktor statis Response.json / Response.error, penghapusan Authorization pada rantai redirect, URL blob URL.createObjectURL, konsumsi body-mixin (text / blob / json / formData / arrayBuffer), Response.clone dengan stream teed structuredClone-d, serta error jaringan XHR sinkron yang dilempar. Setiap subpengujian yang diimpor lulus.

Untuk memperluasnya, masukkan *.any.js baru ke tests/Wpt/fixtures/<category>/ — runner akan mendeteksinya secara otomatis. Suite XHR/Fetch dijalankan oleh tests/Wpt/fetch-server.php (emulator satu file untuk handler resources/*.py WPT); suite WebSocket menggunakan transportasi inert di dalam runner yang menyintesis open/echo/close, cukup untuk fixture yang diimpor. Jalankan kumpulan pengujian itu sendiri:

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

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

Ini langsung berfungsi. Transport bawaan adalah PHP ext-curl. Body mengalir melalui ReadableStream Phasis WHATWG, sehingga for await (const chunk of res.body) juga berfungsi.

Contoh 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) juga diimplementasikan (batas waktu tertunda — diperiksa saat aborted dibaca, bukan dengan memicu peristiwa di tengah event loop; berfungsi untuk transportasi fetch yang memeriksa sinyal selama transfer).

Kontrol embedder (sisi PHP)

Tiga hook pada kelas Phasis\Engine mengontrol perilaku 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);

Jika setFetchTransport() tidak dipanggil, CurlTransport default akan dijalankan. Cookie jar bersifat opsional — tidak ada jar default dan tidak ada cookie yang disimpan kecuali Anda menyediakannya.

Contoh 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

Spesifikasi Streams lengkap: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, serta pipeTo / pipeThrough / tee.

Event loop

setTimeout, setInterval, clearTimeout, clearInterval, dan queueMicrotask ada pada objek global. Microtask (handler Promise, queueMicrotask) dituntaskan sepenuhnya di antara setiap macrotask; timer berjalan sesuai urutan tenggat melalui antrean 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

Digerakkan oleh PhasisEngine::runEventLoop(), yang eval() dan evalAsModule() panggil secara otomatis setelah kode sinkron selesai. Secara default, loop menggunakan waktu virtual — setTimeout(cb, 5000) tidak menunggu PHP; loop memajukan jamnya ke tenggat agar program selesai dengan cepat. Embedder waktu nyata menggerakkan tickEventLoop() sendiri. Lihat ReferensiAPI: Event loop untuk permukaan sisi host.

Yang tidak disertakan

API khusus browser atau model runtime ini sengaja tidak dicakup — lihat Keterbatasan yang diketahui untuk pembahasan lengkap:

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

Sebagian besar dapat diisi dengan polyfill oleh embedder melalui $engine->setGlobal() jika diperlukan.

Mengembangkan kumpulan WPT

tests/Wpt/upstream/ adalah sparse-checkout dari web-platform-tests/wpt yang mencakup fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Untuk memperluas cakupan: salin file *.any.js mana pun dari upstream/<area>/ ke tests/Wpt/fixtures/<category>/. Runner akan mengambilnya pada proses berikutnya; kegagalan dicatat melalui bin/wpt --verbose.