Веб-API

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

Окрім самого ECMAScript, Phasis постачає кілька рівневих наборів API WHATWG / W3C:

Пакет вебплатформи — чисті типи значень без вводу-виводу: 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: дайджест (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 (Stage 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 (Readable/Writable/Transform + BYOB + черги), structuredClone, URL / URLSearchParams, повний API 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 у ланцюжку перенаправлень, URL-адреси blob 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 (емуляторі WPT-обробників resources/*.py в одному файлі); у наборі WebSocket використовується інертний транспорт у виконавці, який імітує відкриття/echo/закриття — цього достатньо для імпортованих тестових сценаріїв. Запустіть корпус самостійно:

Командна оболонка

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. Сховище cookie вмикається явно — типового сховища немає, cookie не зберігаються, якщо ви його не надасте.

Приклад 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 з боку хоста.

Що не постачається

Ці API, доступні лише в браузері або прив’язані до моделі середовища виконання, навмисно не входять до обсягу — повний опис див. у розділі Відомі обмеження:

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

За потреби більшість із них можна поліфілити засобами вбудовувача через $engine->setGlobal().

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

tests/Wpt/upstream/ — це sparse-checkout web-platform-tests/wpt, що охоплює fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Щоб розширити покриття, скопіюйте будь-який файл *.any.js із upstream/<area>/ до tests/Wpt/fixtures/<category>/. Виконавець підхопить його під час наступного запуску; помилки реєструються через bin/wpt --verbose.