API Web

Oltre a ECMAScript, Phasis fornisce diversi pacchetti a livelli di API WHATWG / W3C:

• Pacchetto Web Platform — tipi di valore puri, senza I/O: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
• Pacchetto Fetch — HTTP reali da JavaScript: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, l’intera WHATWG Streams (ReadableStream, WritableStream, TransformStream, strategie di accodamento, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw tramite zlib; brotli quando è caricata l’estensione PECL kjdev/php-ext-brotli), navigator e l’alias globale self conforme alla specifica HTML, oltre a reportError.
• Crypto — crypto.getRandomValues, crypto.randomUUID e l’intera SubtleCrypto: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2, oltre a importazione/esportazione JWK. Basato su ext-openssl.
• WebSocket — costruttore, codifica dei frame RFC 6455, eventi. Il trasporto predefinito usa stream_socket_client; è sostituibile tramite Engine::setWebSocketTransport() per ReactPHP / Ratchet / mock nei test.
• XMLHttpRequest — si basa sul trasporto fetch, quindi si applicano gli stessi hook dei criteri e il trasporto sostituibile.
• Ciclo degli eventi — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Inoltre, AsyncContext (Stage 3) propaga i valori oltre i confini tra microtask e timer.

Tutti i pacchetti sono attivi per impostazione predefinita. Nessun flag, nessuna configurazione: typeof fetch restituisce "function" in una nuova new Engine().

Conformità

Il corpus Web Platform Tests importato (tests/Wpt/fixtures/) copre AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, l’intero standard Streams (Readable/Writable/Transform + BYOB + accodamento), structuredClone, URL / URLSearchParams, l’intera superficie crypto / SubtleCrypto (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2, incluse migliaia di permutazioni di derive-bits da hkdf e pbkdf2), la macchina a stati WebSocket (validazione del costruttore URL e dei sottoprotocolli, semantica dei codici di chiusura, send() per stringhe / ArrayBuffer / viste di array tipizzati / Blob, binaryType, bufferedAmount, chiusura asincrona durante la connessione, nullabilità dei gestori di eventi) e un’ampia parte di Fetch + XMLHttpRequest: macchina a stati di responseType, transizioni di abort/invio, intestazioni consentite da CORS, caricamenti FormData multipart, XMLHttpRequestUpload + ProgressEvent, validazione dell’inizializzazione Response/Headers, costruttori statici Response.json / Response.error, rimozione di Authorization lungo le catene di reindirizzamento, URL blob URL.createObjectURL, consumo dei mixin del corpo (text / blob / json / formData / arrayBuffer), Response.clone con stream suddivisi tramite tee structuredClone-d e generazione di errori di rete per XHR sincrone. Tutti i sottotest importati vengono superati.

Per estendere ulteriormente il corpus, inserite un nuovo *.any.js in tests/Wpt/fixtures/<category>/: il runner lo rileva automaticamente. Le suite XHR/Fetch sono eseguite tramite tests/Wpt/fetch-server.php (un emulatore in un singolo file dei gestori resources/*.py del WPT); la suite WebSocket usa un trasporto inattivo nel runner che simula apertura/eco/chiusura, sufficiente per i fixture importati. Eseguite il corpus in autonomia:

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

Esempio di 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();

Funziona subito. Il trasporto predefinito è PHP ext-curl. I corpi vengono trasmessi in streaming tramite WHATWG ReadableStream fornito da Phasis, quindi funziona anche for await (const chunk of res.body).

Esempio di 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
  }
}

Anche AbortSignal.timeout(ms) è implementato (scadenza differita: verifica alla lettura aborted, invece di attivare un evento nel mezzo del ciclo degli eventi; funziona con i trasporti fetch che controllano il segnale durante il trasferimento).

Controlli dell’host (lato PHP)

Tre hook sulla classe Phasis\Engine controllano il comportamento di 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 non viene chiamato setFetchTransport(), viene usato il valore predefinito CurlTransport. Il contenitore dei cookie è facoltativo: non ne viene creato uno per impostazione predefinita e non vengono memorizzati cookie a meno che non ne forniate uno.

Esempio di 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

Specifica Streams completa: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, oltre a pipeTo / pipeThrough / tee.

Ciclo di eventi

setTimeout, setInterval, clearTimeout, clearInterval e queueMicrotask sono nell’oggetto globale. Le microtask (gestori Promise, queueMicrotask) vengono eseguite fino al completamento tra ogni macrotask; i timer scattano in ordine di scadenza tramite una coda per 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

Gestito dal Engine::runEventLoop() di Phasis, che eval() e evalAsModule() richiamano automaticamente al termine del codice sincrono. Il ciclo usa tempo virtuale per impostazione predefinita: setTimeout(cb, 5000) non attende PHP; porta l'orologio alla scadenza, così il programma termina rapidamente. Gli ambienti integrati in tempo reale gestiscono direttamente tickEventLoop(). Per l'interfaccia lato host, consultate API: ciclo di eventi.

Cosa non viene fornito

Queste API, disponibili solo nel browser o legate al modello di runtime, sono intenzionalmente escluse dall’ambito: consultate Limitazioni note per la spiegazione completa:

• window, document, l’albero DOM
• localStorage, sessionStorage, IndexedDB
• Worker, SharedWorker, MessageChannel
• Service Worker, Push API, notifiche, BroadcastChannel

Se necessario, l’host può fornire polyfill per la maggior parte di queste API tramite $engine->setGlobal().

Ampliare il corpus WPT

tests/Wpt/upstream/ è un checkout parziale di web-platform-tests/wpt che copre fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/. Per ampliare la copertura: copiate qualsiasi file *.any.js da upstream/<area>/ a tests/Wpt/fixtures/<category>/. Il runner lo rileva alla successiva esecuzione; gli errori vengono registrati tramite bin/wpt --verbose.