APIs da Web

Além do próprio ECMAScript, Phasis oferece vários pacotes em camadas de APIs WHATWG / W3C:

• Pacote Web Platform — tipos de valores puros, sem E/S: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Pacote Fetch — HTTP real de JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, Streams WHATWG completos (ReadableStream, WritableStream, TransformStream, estratégias de enfileiramento, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw via zlib; brotli quando a extensão PECL kjdev/php-ext-brotli está carregada), navigator e o alias global da especificação HTML self + reportError.
• Criptografia — crypto.getRandomValues, crypto.randomUUID e SubtleCrypto completo: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — além da importação/exportação de JWK. Com suporte de ext-openssl.
• WebSocket — construtor, codec de quadros RFC 6455, eventos. O transporte padrão usa stream_socket_client; pode ser substituído por Engine::setWebSocketTransport() para ReactPHP / Ratchet / mocks em testes.
• XMLHttpRequest — implementado sobre o transporte fetch, então os mesmos ganchos de política e o transporte substituível se aplicam.
• Loop de eventos — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Além de AsyncContext (Stage 3), que propaga valores entre limites de microtarefas / temporizadores.

Todos os pacotes vêm ativados por padrão. Sem sinalizador, sem configuração — typeof fetch retorna "function" em um new Engine() recém-criado.

Conformidade

O corpus importado Web Platform Tests (tests/Wpt/fixtures/) cobre AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, o padrão Streams completo (Readable/Writable/Transform + BYOB + enfileiramento), structuredClone, URL / URLSearchParams, toda a superfície de crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — incluindo milhares de permutações de derive-bits de hkdf e pbkdf2), a máquina de estados de WebSocket (construtor URL e validação de subprotocolos, semântica dos códigos de fechamento, send() para strings / ArrayBuffer / visualizações de arrays tipados / Blob, binaryType, bufferedAmount, fechamento assíncrono durante a conexão, possibilidade de valores nulos em manipuladores de eventos) e uma ampla parte de Fetch + XMLHttpRequest — máquina de estados de responseType, transições de abort/send, cabeçalhos permitidos por CORS, uploads multipart de FormData, XMLHttpRequestUpload + ProgressEvent, validação de inicialização de Response/Headers, construtores estáticos Response.json / Response.error, remoção de Authorization na cadeia de redirecionamentos, URLs blob URL.createObjectURL, consumo de body-mixin (text / blob / json / formData / arrayBuffer), Response.clone com streams divididos por structuredClone e lançamento de erro de rede em XHR síncrono. Todos os subtestes importados passam.

Para ampliar a cobertura, adicione um novo *.any.js a tests/Wpt/fixtures/<category>/ — o executor o detecta automaticamente. As suítes de XHR/Fetch são conduzidas por tests/Wpt/fetch-server.php (um emulador em arquivo único dos manipuladores resources/*.py de WPT); a suíte de WebSocket usa um transporte inerte dentro do executor que simula abertura/eco/fechamento, suficiente para os fixtures importados. Execute o corpus você mesmo:

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

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

Isso funciona imediatamente. O transporte padrão é PHP ext-curl. Os corpos são transmitidos pelos ReadableStream WHATWG que Phasis oferece, então for await (const chunk of res.body) também funciona.

Exemplo de 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) também está implementado (prazo final sob demanda — verifica na leitura aborted, em vez de disparar um evento no meio do loop de eventos; funciona com transportes fetch que consultam o sinal durante a transferência).

Controles do embedder (lado PHP)

Três ganchos na classe Phasis\Engine controlam o comportamento de 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);

Se setFetchTransport() não for chamado, o CurlTransport padrão é executado. O armazenamento de cookies é opt-in — não há armazenamento padrão, e nenhum cookie é guardado se você não fornecer um.

Exemplo de 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

Especificação completa de Streams: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, além de pipeTo / pipeThrough / tee.

Loop de eventos

setTimeout, setInterval, clearTimeout, clearInterval e queueMicrotask estão no objeto global. As microtarefas (manipuladores de Promise, queueMicrotask) são esvaziadas até o fim entre cada macrotarefa; os temporizadores disparam na ordem dos prazos por meio de uma fila por realm.

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

Conduzido pelo Engine::runEventLoop() de Phasis, que chama eval() e evalAsModule() automaticamente após a conclusão do código síncrono. Por padrão, o loop usa tempo virtual — setTimeout(cb, 5000) não espera PHP; o loop adianta o relógio até o prazo para que o programa termine rapidamente. Embedders em tempo real controlam tickEventLoop() por conta própria. Consulte Referência: loop de eventosAPI para a interface do lado do host.

O que não é fornecido

Estas APIs exclusivas do navegador ou do modelo de execução estão deliberadamente fora do escopo — consulte Limitações conhecidas para a discussão completa:

• window, document, a árvore DOM
• localStorage, sessionStorage, IndexedDB
• Worker, SharedWorker, MessageChannel
• Service Workers, Push API, Notificações, BroadcastChannel

A maioria desses recursos pode receber polyfills do embedder via $engine->setGlobal(), se necessário.

Expandindo o corpus WPT

tests/Wpt/upstream/ é um checkout esparso de web-platform-tests/wpt que cobre fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Para ampliar a cobertura: copie qualquer arquivo *.any.js de upstream/<area>/ para tests/Wpt/fixtures/<category>/. O executor o detectará na próxima execução; as falhas são registradas via bin/wpt --verbose.