Treci la conținut

API-uri Web

Vizualizați ca Markdown Editați pe GitHub Documentație la 5b53f69

Dincolo de ECMAScript în sine, Phasis include mai multe pachete stratificate de API-uri WHATWG / W3C:

  • Pachetul Web Platform — tipuri de valori pure, fără I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
  • Pachetul Fetch — HTTP real prin JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, WHATWG Streams complet (ReadableStream, WritableStream, TransformStream, strategii de punere în coadă, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw prin zlib; brotli când este încărcată extensia PECL kjdev/php-ext-brotli), navigator și aliasul global self conform specificației HTML + reportError.
  • Crypto — crypto.getRandomValues, crypto.randomUUID și SubtleCrypto complet: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — plus import/export JWK. Bazat pe ext-openssl.
  • WebSocket — constructor, codec de cadre RFC 6455, evenimente. Transportul implicit folosește stream_socket_client; poate fi înlocuit prin Engine::setWebSocketTransport() pentru ReactPHP / Ratchet / mock-uri în teste.
  • XMLHttpRequest — stratificat peste transportul fetch, astfel încât se aplică aceleași hook-uri de politică și același transport înlocuibil.
  • Bucla de evenimente — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. În plus, AsyncContext (etapa 3) propagă valorile între limitele microtask-urilor / timerelor.

Toate pachetele sunt activate implicit. Fără fanioane sau configurare — typeof fetch returnează "function" pentru un new Engine() nou.

Conformitate

Corpusul importat de Web Platform Tests (tests/Wpt/fixtures/) acoperă AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, standardul Streams complet (Readable/Writable/Transform + BYOB + strategii de punere în coadă), structuredClone, URL / URLSearchParams, întreaga suprafață crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — inclusiv mii de permutări derive-bits din hkdf și pbkdf2), mașina de stări WebSocket (constructor URL și validarea subprotocolului, semantica codurilor de închidere, send() pentru șiruri / ArrayBuffer / vizualizări de matrice tipizată / Blob, binaryType, bufferedAmount, închidere asincronă în timpul conectării, posibilitatea ca handler-ele de evenimente să fie null) și o secțiune amplă din Fetch + XMLHttpRequest — mașina de stări responseType, tranzițiile abort/send, antetele permise în siguranță de CORS, încărcări multipart FormData, XMLHttpRequestUpload + ProgressEvent, validarea inițializării Response/Headers, constructorii statici Response.json / Response.error, eliminarea antetului Authorization în lanțurile de redirecționare, URL-uri blob URL.createObjectURL, consumarea mixin-ului pentru corp (text / blob / json / formData / arrayBuffer), Response.clone cu fluxuri duplicate prin tee și structuredClone, precum și aruncarea erorilor de rețea pentru XHR sincron. Toate subtestele importate trec.

Pentru a extinde suita, adăugați un fișier *.any.js nou în tests/Wpt/fixtures/<category>/ — rularea îl preia automat. Suitele XHR/Fetch sunt conduse de tests/Wpt/fetch-server.php (un emulator într-un singur fișier pentru handler-ele resources/*.py WPT); suita WebSocket folosește un transport inert în runner, care sintetizează open/echo/close și este suficient pentru fixture-urile importate. Rulați corpusul:

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

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

Funcționează imediat. Transportul implicit este PHP ext-curl. Corpurile sunt transmise în flux prin WHATWG ReadableStream Phasis oferă, așa că funcționează și for await (const chunk of res.body).

Exemplu 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) este implementat și el (termen-limită leneș — verifică la citirea aborted, în loc să emită un eveniment în mijlocul buclei de evenimente; funcționează pentru transporturile fetch care verifică semnalul în timpul transferului).

Controale pentru integrator (partea PHP)

Trei hook-uri în clasa Phasis\Engine controlează comportamentul 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);

Dacă nu se apelează setFetchTransport(), se execută implicit CurlTransport. Borcanul de cookie-uri este opțional — nu există unul implicit și nu se stochează cookie-uri dacă nu furnizați unul.

Exemplu 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

Specificația Streams completă: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, plus pipeTo / pipeThrough / tee.

Bucla de evenimente

setTimeout, setInterval, clearTimeout, clearInterval și queueMicrotask se află pe obiectul global. Microtask-urile (handler-ele Promise, queueMicrotask) se execută până la capăt între fiecare macrotask; timerele se declanșează în ordinea termenelor-limită printr-o coadă 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

Condusă de Phasis prin Engine::runEventLoop(), care apelează automat eval() și evalAsModule() după terminarea codului sincron. Bucla folosește implicit timp virtual — setTimeout(cb, 5000) nu așteaptă PHP; bucla își avansează ceasul până la termenul-limită, astfel încât programul se încheie rapid. Integratorii în timp real rulează singuri tickEventLoop(). Consultați API: Bucla de evenimente pentru interfața gazdei.

Ce nu este inclus

Aceste API-uri specifice browserului sau modelului de execuție sunt excluse în mod deliberat — consultați Limitări cunoscute pentru detalii complete:

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

Majoritatea pot fi implementate ca polyfill de către integrator prin $engine->setGlobal(), dacă este nevoie.

Extinderea corpusului WPT

tests/Wpt/upstream/ este un sparse-checkout al web-platform-tests/wpt, care acoperă fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Pentru a extinde acoperirea, copiați orice fișier *.any.js din upstream/<area>/ în tests/Wpt/fixtures/<category>/. Rularea îl va prelua data viitoare; eșecurile sunt înregistrate prin bin/wpt --verbose.