Уеб API

Преглед като Markdown Редактиране в GitHub Документация за 5b53f69

Освен самия ECMAScript, Phasis предоставя няколко слоя WHATWG / W3C API:

Пакет Web Platform — чисти типове стойности, без I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
Пакет Fetch — реален HTTP от JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, пълни WHATWG Streams (ReadableStream, WritableStream, TransformStream, стратегии за опашки, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw чрез zlib; brotli при заредено разширение PECL kjdev/php-ext-brotli), navigator и глобален псевдоним по спецификация HTML-self + reportError.
Криптография — crypto.getRandomValues, crypto.randomUUID и пълен SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — плюс импорт/експорт на JWK. Реализирано чрез ext-openssl.
WebSocket — конструктор, кодек за кадри по RFC 6455, събития. Транспортът по подразбиране използва stream_socket_client; може да бъде заменен чрез Engine::setWebSocketTransport() за ReactPHP / Ratchet / тестови моки.
XMLHttpRequest — надграден върху fetch транспорта, така че важат същите куки за правила и сменяем транспорт.
Цикъл на събитията — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Освен това AsyncContext (етап 3) пренася стойности през границите на микрозадачи / таймери.

Всички пакети са включени по подразбиране. Без флагове и настройки — typeof fetch връща "function" в нов new Engine().

Съответствие

Импортираният корпус Web Platform Tests (tests/Wpt/fixtures/) обхваща AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, пълния Streams Standard (Readable/Writable/Transform + BYOB + опашки), structuredClone, URL / URLSearchParams, цялата повърхност на crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — включително хиляди варианти на derive-bits от hkdf и pbkdf2), машината на състоянията на WebSocket (конструктор URL и проверка на подпротокола, семантика на кодовете за затваряне, send() за низове / ArrayBuffer / изгледи на типизирани масиви / Blob, binaryType, bufferedAmount, асинхронно затваряне при свързване, допустимост на null за обработчиците на събития) и широка част от Fetch + XMLHttpRequest — машина на състоянията на responseType, преходи при прекъсване/изпращане, заглавки в списъка с позволени за CORS, качвания на multipart FormData, XMLHttpRequestUpload + ProgressEvent, проверка на инициализацията на Response/Headers, статичните конструктори Response.json / Response.error, премахване на Authorization при верига от пренасочвания, blob URL адреси URL.createObjectURL, консумиране на body-mixin (text / blob / json / formData / arrayBuffer), Response.clone с потоци, дублирани чрез structuredClone-d, и хвърляне на мрежова грешка при синхронен XHR. Всеки импортиран подтест преминава.

За да разширите корпуса, добавете нов *.any.js в tests/Wpt/fixtures/<category>/ — изпълнителят ще го открие автоматично. Наборите XHR/Fetch се управляват от tests/Wpt/fetch-server.php (емулатор в един файл на обработчиците resources/*.py на WPT); наборът WebSocket използва неактивен транспорт в изпълнителя, който симулира отваряне/ехо/затваряне и е достатъчен за импортираните фикстури. Изпълнете корпуса сами:

Обвивка

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

Пример с 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();

Работи веднага. Транспортът по подразбиране е PHP ext-curl. Тялото се предава поточно чрез WHATWG ReadableStream, които Phasis предоставя, така че работи и for await (const chunk of res.body).

Пример с 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) също е реализиран (с мързелив краен срок — проверява при всяко aborted прочитане, вместо да задейства събитие по средата на цикъла на събитията; работи с fetch транспортите, които проверяват сигнала по време на преноса).

Контроли за вграждане (страна PHP)

Три куки в класа Phasis\Engine управляват поведението на 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);

Ако не се извика setFetchTransport(), се използва стандартният CurlTransport. Хранилището за бисквитки е по избор — няма хранилище по подразбиране и бисквитки не се записват, освен ако не предоставите такова.

Пример за 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

Пълна спецификация на Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, плюс pipeTo / pipeThrough / tee.

Цикъл на събитията

setTimeout, setInterval, clearTimeout, clearInterval и queueMicrotask са в глобалния обект. Микрозадачите (обработчиците на Promise, queueMicrotask) се изпълняват докрай между всяка макрозадача; таймерите се задействат по реда на крайните срокове чрез опашка за всяка среда.

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

Управлява се от Phasis и неговия Engine::runEventLoop(), който автоматично извиква eval() и evalAsModule() след приключване на синхронния код. По подразбиране цикълът използва виртуално време — setTimeout(cb, 5000) не изчаква PHP; цикълът премества часовника си до крайния срок, за да завърши програмата бързо. Средите за вграждане в реално време управляват tickEventLoop() сами. Вижте API: Цикъл на събитията за интерфейса от страната на хоста.

Какво не се предоставя

Тези API-та, предназначени само за браузър или свързани с модела на изпълнение, умишлено са извън обхвата — вижте Известни ограничения за пълното описание:

window, document, дървото на DOM
localStorage, sessionStorage, IndexedDB
Worker, SharedWorker, MessageChannel
Service Workers, Push API, Notifications, BroadcastChannel

При нужда повечето от тях могат да се полифилират от средата за вграждане чрез $engine->setGlobal().

Разширяване на корпуса WPT

tests/Wpt/upstream/ е оскъдно извлечено копие на web-platform-tests/wpt, което обхваща fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. За да разширите покритието: копирайте произволен файл *.any.js от upstream/<area>/ в tests/Wpt/fixtures/<category>/. Изпълнителят ще го открие при следващото стартиране; неуспешните тестове се записват чрез bin/wpt --verbose.