Przejdź do treści

Interfejsy API platformy WWW

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 5b53f69

Poza samym ECMAScript Phasis dostarcza kilka warstwowych pakietów interfejsów API WHATWG / W3C:

  • Pakiet platformy WWW — czyste typy wartości, bez wejścia/wyjścia: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Pakiet Fetch — rzeczywiste HTTP z JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, pełne WHATWG Streams (ReadableStream, WritableStream, TransformStream, strategie kolejkowania, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw przez zlib; brotli, gdy załadowane jest rozszerzenie PECL kjdev/php-ext-brotli), navigator oraz globalny alias self zgodny ze specyfikacją HTML wraz z reportError.
  • Crypto — crypto.getRandomValues, crypto.randomUUID oraz pełna obsługa SubtleCrypto: skróty (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — oraz import/eksport JWK. Oparte na ext-openssl.
  • WebSocket — konstruktor, koder ramek RFC 6455, zdarzenia. Domyślny transport używa stream_socket_client; można go wymienić przez Engine::setWebSocketTransport() na potrzeby ReactPHP / Ratchet / atrap w testach.
  • XMLHttpRequest — warstwa nad transportem fetch, dzięki czemu obowiązują te same zaczepy zasad i możliwość wymiany transportu.
  • Pętla zdarzeń — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Ponadto AsyncContext (etap 3) przenosi wartości przez granice mikrozadań / timerów.

Wszystkie pakiety są domyślnie włączone. Bez flag i konfiguracji — świeży obiekt new Engine() zwracany przez typeof fetch ma dostęp do "function".

Zgodność

Zaimportowany korpus Web Platform Tests (tests/Wpt/fixtures/) obejmuje AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, pełny standard Streams (Readable/Writable/Transform + BYOB + kolejkowanie), structuredClone, URL / URLSearchParams, pełny zakres crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — w tym tysiące permutacji derive-bits z hkdf i pbkdf2), maszynę stanów WebSocket (konstruktor URL i walidację podprotokołu, semantykę kodów zamknięcia, send() dla ciągów znaków / ArrayBuffer / widoków tablic typowanych / Blob, binaryType, bufferedAmount, asynchroniczne zamykanie podczas łączenia, dopuszczanie wartości null dla obsługi zdarzeń) oraz szeroki zakres Fetch + XMLHttpRequest — maszynę stanów responseType, przejścia anulowania/wysyłania, nagłówki dozwolone przez CORS, wysyłanie multipart FormData, XMLHttpRequestUpload + ProgressEvent, walidację init Response/Headers, statyczne konstruktory Response.json / Response.error, usuwanie Authorization z łańcucha przekierowań, adresy URL blobów URL.createObjectURL, odczytywanie treści przez body-mixin (text / blob / json / formData / arrayBuffer), strumienie dzielone przez structuredClone-d Response.clone oraz zgłaszanie błędu sieciowego przez synchroniczne XHR. Wszystkie zaimportowane podtesty przechodzą.

Aby rozszerzyć zestaw, dodaj nowy plik *.any.js do tests/Wpt/fixtures/<category>/ — runner wykryje go automatycznie. Zestawy XHR/Fetch obsługuje tests/Wpt/fetch-server.php (jednoplikowy emulator procedur obsługi resources/*.py WPT); zestaw WebSocket korzysta z nieaktywnego transportu wbudowanego w runner, który symuluje otwarcie/odpowiedź/zamknięcie i wystarcza do zaimportowanych zestawów testowych. Uruchom korpus samodzielnie:

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

Przykład 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();

Działa od razu. Domyślnym transportem jest PHP ext-curl. Treści są przesyłane strumieniowo przez WHATWG ReadableStream dostarczane przez Phasis, więc działa też for await (const chunk of res.body).

Przykład 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) także jest zaimplementowane (termin sprawdzany leniwie — kontrola przy każdym aborted odczycie zamiast wywoływania zdarzenia w środku pętli zdarzeń; działa w przypadku transportów fetch, które podczas przesyłania sprawdzają sygnał).

Sterowanie przez osadzający program (strona PHP)

Trzy zaczepy w klasie Phasis\Engine sterują zachowaniem 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);

Jeśli nie wywołano setFetchTransport(), uruchamia się domyślny CurlTransport. Słoik na pliki cookie jest opcjonalny — domyślnie nie ma słoika ani zapisywanych plików cookie, dopóki go nie dostarczysz.

Przykład strumieni

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

Pełna specyfikacja Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, a także pipeTo / pipeThrough / tee.

Pętla zdarzeń

setTimeout, setInterval, clearTimeout, clearInterval i queueMicrotask są dostępne w obiekcie globalnym. Mikrozadania (obsługi Promise, queueMicrotask) są wykonywane do końca między każdym makrozadaniem; timery uruchamiają się według terminów za pośrednictwem kolejki przypisanej do danego 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

Sterowanie odbywa się przez Engine::runEventLoop() obiektu Phasis; metody eval() i evalAsModule() wywołują ją automatycznie po zakończeniu kodu synchronicznego. Domyślnie pętla używa czasu wirtualnego — setTimeout(cb, 5000) nie usypia PHP; pętla przesuwa zegar do wyznaczonego terminu, dzięki czemu program kończy się szybko. Osadzające programy działające w czasie rzeczywistym samodzielnie sterują tickEventLoop(). Interfejs po stronie hosta opisano na stronie API: Pętla zdarzeń.

Czego nie ma w pakiecie

Te interfejsy API dostępne tylko w przeglądarce lub związane z modelem środowiska wykonawczego celowo pominięto — pełne omówienie znajdziesz w sekcji Znane ograniczenia:

  • window, document, drzewo DOM
  • localStorage, sessionStorage, IndexedDB
  • Worker, SharedWorker, MessageChannel
  • Service Workers, interfejs Push API, powiadomienia, BroadcastChannel

W razie potrzeby większość z nich można wypełnić polyfillami po stronie programu osadzającego za pomocą $engine->setGlobal().

Rozbudowa korpusu WPT

tests/Wpt/upstream/ to częściowe pobranie web-platform-tests/wpt obejmujące fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/ i dom/events/. Aby rozszerzyć zakres, skopiuj dowolny plik *.any.js z upstream/<area>/ do tests/Wpt/fixtures/<category>/. Runner wykryje go przy następnym uruchomieniu; błędy są zapisywane przez bin/wpt --verbose.