Pereiti prie turinio

Žiniatinklio API

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: 5b53f69

Be paties ECMAScript, Phasis pateikia kelis sluoksniuotus WHATWG / W3C API paketus:

  • Žiniatinklio platformos paketas — grynųjų reikšmių tipai, be įvesties ir išvesties: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Fetch paketas — tikras HTTP iš JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, visas WHATWG srautų API (ReadableStream, WritableStream, TransformStream, eilių strategijos, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw per zlib; brotli, kai įkeliamas kjdev/php-ext-brotli PECL plėtinys), navigator ir HTML specifikacijos self globalus pseudonimas bei reportError.
  • Kriptografija — crypto.getRandomValues, crypto.randomUUID ir visas SubtleCrypto: santrauka (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 ir JWK importavimas / eksportavimas. Pagrįsta ext-openssl.
  • WebSocket — konstruktorius, RFC 6455 kadrų koduotuvas, įvykiai. Pagal numatytąsias nuostatas transportui naudojamas stream_socket_client; jį galima pakeisti per Engine::setWebSocketTransport(), kad tiktų ReactPHP / Ratchet / netikriesiems objektams testuose.
  • XMLHttpRequest — sluoksniuota virš Fetch transporto, todėl taikomi tie patys politikos kabliai ir pakeičiamas transportas.
  • Įvykių ciklas — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Be to, AsyncContext (3 etapas) perduoda reikšmes per mikroužduočių / laikmačių ribas.

Visi paketai įjungti pagal numatytąsias nuostatas. Nereikia nei vėliavėlės, nei sąrankos — typeof fetch naujame new Engine() pateikia "function".

Atitiktis

Importuotas Web Platform Tests rinkinys (tests/Wpt/fixtures/) apima AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, visą Streams Standard (Readable/Writable/Transform + BYOB + eilių valdymą), structuredClone, URL / URLSearchParams, visą crypto / SubtleCrypto sąsają (santrauka, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2, įskaitant tūkstančius išvedimo bitų permutacijų iš hkdf ir pbkdf2), WebSocket būsenų automatą (konstruktoriaus URL ir subprotokolo tikrinimą, uždarymo kodų semantiką, send() eilutėms / ArrayBuffer / tipuotų masyvų rodiniams / Blob, binaryType, bufferedAmount, asinchroninį uždarymą prisijungiant, apdorojimo funkcijų null reikšmes) ir plačią Fetch + XMLHttpRequest dalį — responseType būsenų automatą, atšaukimo / siuntimo perėjimus, CORS leidžiamų antraščių sąrašą, multipart FormData įkėlimus, XMLHttpRequestUpload + ProgressEvent, pradinės konfigūracijos tikrinimą Response/Headers, statinius konstruktorius Response.json / Response.error, Authorization antraštės pašalinimą iš peradresavimų sekos, URL.createObjectURL blob URL, turinio mišinio skaitymą (text / blob / json / formData / arrayBuffer), Response.clone su structuredClone pagrįstais padalytais srautais ir sinchroninį XHR tinklo klaidos išmetimą. Visi importuoti papildomi testai sėkmingai vykdomi.

Norėdami išplėsti aprėptį, įdėkite naują *.any.js į tests/Wpt/fixtures/<category>/ — paleidimo programa jį aptiks automatiškai. XHR/Fetch rinkinius valdo tests/Wpt/fetch-server.php (vieno failo WPT resources/*.py apdorojimo funkcijų emuliatorius); WebSocket rinkiniui naudojamas neveikiantis transportas paleidimo programoje, imituojantis atidarymą / aido atsakymą / uždarymą ir tinkamas importuotiems bandymų rinkiniams. Paleiskite rinkinį patys:

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

fetch() pavyzdys

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

Veikia iš karto. Pagal numatytąsias nuostatas transportas yra PHP ext-curl. Turiniai srautiniu būdu perduodami per WHATWG ReadableStream, kurį teikia Phasis, todėl veikia ir for await (const chunk of res.body).

AbortController pavyzdys

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) taip pat įgyvendintas (atidėtas patikrinimas pagal terminą — tikrinama skaitant aborted, o ne siunčiant įvykį įvykių ciklo viduryje; veikia su Fetch transportais, kurie perdavimo metu tikrina signalą).

Įterpimo aplinkos valdikliai (PHP pusė)

Trys kabliukai klasėje Phasis\Engine valdo fetch veikimą:

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

Jei setFetchTransport() neiškviečiamas, vykdomas numatytasis CurlTransport. Slapukų saugykla pasirenkama — pagal numatytuosius nustatymus ji nenaudojama, slapukai nesaugomi, nebent ją pateikiate.

Streams pavyzdys

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

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

Įvykių ciklas

setTimeout, setInterval, clearTimeout, clearInterval ir queueMicrotask yra globaliame objekte. Mikroužduotys (Promise apdorojimo funkcijos, queueMicrotask) visiškai įvykdomos tarp kiekvienų makroužduočių; laikmačiai suveikia terminų tvarka pagal kiekvienos aplinkos eilę.

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

Veikia Phasis Engine::runEventLoop(), kurią eval() ir evalAsModule() iškviečia automatiškai, kai baigiamas sinchroninis kodas. Pagal numatytuosius nustatymus ciklas naudoja virtualųjį laiką — setTimeout(cb, 5000) nelaukia PHP; ciklas pasuka laikrodį iki termino, todėl programa greitai baigiama. Realaus laiko įterptosios aplinkos pačios valdo tickEventLoop(). Žr. : Įvykių ciklasAPI, kur aprašyta pagrindinės aplinkos sąsaja.

Kas nepateikiama

Šios tik naršyklėse arba vykdymo aplinkos modelyje veikiančios API sąmoningai nepatenka į apimtį — išsamiau žr. Žinomi apribojimai:

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

Jei reikia, daugumą jų įterpianti programa gali įgyvendinti naudodama $engine->setGlobal().

WPT rinkinio plėtra

tests/Wpt/upstream/ yra dalinė web-platform-tests/wpt išskaita, apimanti fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Norėdami išplėsti aprėptį, nukopijuokite bet kurį *.any.js failą iš upstream/<area>/ į tests/Wpt/fixtures/<category>/. Vykdyklė jį aptiks kitą kartą paleista; klaidos registruojamos per bin/wpt --verbose.