Веб-API

Помимо самой 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: 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 (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 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, переходы abort/send, заголовки из списка разрешенных CORS, отправка файлов FormData в формате multipart, XMLHttpRequestUpload + ProgressEvent, проверка инициализации Response/Headers, статические конструкторы Response.json / Response.error, удаление Authorization при перенаправлении по цепочке, blob-URL URL.createObjectURL, чтение тела через примеси (text / blob / json / formData / arrayBuffer), потоки с tee structuredClone для Response.clone и выброс ошибки сети в синхронном XHR. Все импортированные подтесты проходят.

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

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

Пример fetch()

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

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:

$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

// 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) выполняются до конца между каждой макрозадачей; таймеры срабатывают по сроку через очередь текущей области.

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.