Web API'leri

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 5b53f69

ECMAScript'in ötesinde, Phasis çeşitli katmanlı WHATWG / W3C API paketleri sunar:

Web Platformu Paketi — G/Ç içermeyen saf değer türleri: URL, URLSearchParams, URLPattern, TextEncoder, TextDecoder, atob, btoa, structuredClone, performance, DOMException.
Fetch Paketi — JavaScript'den gerçek HTTP: fetch, Request, Response, Headers, Body, AbortController, AbortSignal, Blob, File, FormData, EventTarget, Event, WHATWG Streams'in tamamı (ReadableStream, WritableStream, TransformStream, kuyruk stratejileri, BYOB), CompressionStream / DecompressionStream (gzip / deflate / deflate-raw için zlib; kjdev/php-ext-brotli PECL uzantısı yüklüyse brotli), navigator ve HTML spesifikasyonundaki self genel takma adı + reportError.
Crypto — crypto.getRandomValues, crypto.randomUUID ve SubtleCrypto'ın tamamı: özet (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — ayrıca JWK içe/dışa aktarma. ext-openssl desteğiyle çalışır.
WebSocket — kurucu, RFC 6455 çerçeve kodlayıcısı, etkinlikler. Varsayılan taşıma için stream_socket_client kullanılır; ReactPHP / Ratchet / testlerdeki taklitler için Engine::setWebSocketTransport() üzerinden değiştirilebilir.
XMLHttpRequest — fetch taşımasının üzerine katmanlanır; böylece aynı ilke kancaları ve değiştirilebilir taşıma uygulanır.
Olay döngüsü — setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask. Ayrıca mikro görev / zamanlayıcı sınırları boyunca değerleri aktaran AsyncContext (Aşama 3).

Tüm paketler varsayılan olarak açıktır. Bayrak veya kurulum gerekmez — new Engine() yeniyken typeof fetch, "function" döndürür.

Uygunluk

İçe aktarılan Web Platform Tests külliyatı (tests/Wpt/fixtures/) şunları kapsar: AbortController / AbortSignal, atob / btoa, Blob / File, TextEncoder / TextDecoder, EventTarget / Event, FormData, Headers, performance.now, Streams Standard'ın tamamı (Readable/Writable/Transform + BYOB + kuyruklama), structuredClone, URL / URLSearchParams, crypto / SubtleCrypto yüzeyinin tamamı (özet, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — hkdf ve pbkdf2'ten türetilen binlerce bit türetme permütasyonu dahil), WebSocket durum makinesi (kurucu URL ve alt protokol doğrulaması, kapatma kodu semantiği, dizeler için send() / ArrayBuffer / türlenmiş dizi görünümleri / Blob, binaryType, bufferedAmount, bağlantı kurulurken asenkron kapatma, olay işleyicilerinin null olabilirliği) ve Fetch + XMLHttpRequest yüzeyinin geniş bir bölümü — responseType durum makinesi, iptal/gönderim geçişleri, CORS açısından güvenli başlıklar, çok parçalı FormData yüklemeleri, XMLHttpRequestUpload + ProgressEvent, Response/Headers başlatma doğrulaması, statik Response.json / Response.error kurucuları, yönlendirme zincirinde Authorization başlığının çıkarılması, URL.createObjectURL blob URL'leri, gövde karışımı tüketimi (text / blob / json / formData / arrayBuffer), structuredClone ile Response.clone teeli akışlar ve eşzamanlı XHR ağ hatası fırlatma. İçe aktarılan tüm alt testler başarılı.

Daha fazla kapsam eklemek için yeni bir *.any.js dosyasını tests/Wpt/fixtures/<category>/ içine koyun — çalıştırıcı dosyayı otomatik olarak bulur. XHR/Fetch paketlerini tests/Wpt/fetch-server.php sürücülendirir (WPT resources/*.py işleyicilerinin tek dosyalı emülatörü); WebSocket paketi, içe aktarılan fikstürler için yeterli olan açılma/yankı/kapatma olaylarını oluşturan etkisiz bir çalıştırıcı içi taşıma kullanır. Külliyatı kendiniz çalıştırın:

Kabuk

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

fetch() örneği

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

Bu, ek ayar gerektirmeden çalışır. Varsayılan taşıma PHP ext-curl'dir. Gövdeler, Phasis'ın sunduğu WHATWG ReadableStream üzerinden akar; dolayısıyla for await (const chunk of res.body) da çalışır.

AbortController örneği

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) da uygulanmıştır (tembel son tarih — olay döngüsünün ortasında bir olay tetiklemek yerine aborted okumasında denetler; aktarım sırasında sinyali yoklayan fetch taşımalarında çalışır).

Gömücü denetimleri (PHP tarafı)

Phasis\Engine sınıfındaki üç kanca fetch davranışını denetler:

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() çağrılmazsa varsayılan CurlTransport çalışır. Çerez kavanozu isteğe bağlıdır — varsayılan kavanoz yoktur; siz sağlamadıkça hiçbir çerez saklanmaz.

Streams örneği

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 spesifikasyonunun tamamı: ReadableStream, WritableStream, TransformStream, ReadableStreamDefaultController, ReadableByteStreamController, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, WritableStreamDefaultController, WritableStreamDefaultWriter, TransformStreamDefaultController, ByteLengthQueuingStrategy, CountQueuingStrategy, ayrıca pipeTo / pipeThrough / tee.

Olay döngüsü

setTimeout, setInterval, clearTimeout, clearInterval ve queueMicrotask global nesnede bulunur. Mikro görevler (Promise işleyicileri, queueMicrotask) her makro görev arasında tamamlanana kadar işlenir; zamanlayıcılar, realm başına bir kuyrukta son tarih sırasına göre çalışır.

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'ın Engine::runEventLoop()'i tarafından yönetilir; bu, eşzamanlı kod tamamlandıktan sonra eval() ve evalAsModule() çağrılarını otomatik olarak yapar. Döngü varsayılan olarak sanal zaman kullanır — setTimeout(cb, 5000) PHP uyumaz; programın hızla tamamlanması için döngü saatini son tarihe ilerletir. Gerçek zamanlı gömücüler tickEventLoop()'i kendileri çalıştırır. Ana makine tarafındaki yüzey için API: Olay döngüsü bölümüne bakın.

Sunulmayanlar

Yalnızca tarayıcıda bulunan veya çalışma zamanı modeline özgü bu API'ler özellikle kapsam dışında tutulmuştur — ayrıntılı açıklama için Bilinen sınırlamalar bölümüne bakın:

window, document, DOM ağacı
localStorage, sessionStorage, IndexedDB
Worker, SharedWorker, MessageChannel
Service Workers, Push API, Notifications, BroadcastChannel

Bunların çoğu gerekirse gömücü tarafından $engine->setGlobal() ile çoklanabilir.

WPT külliyatını genişletme

tests/Wpt/upstream/, web-platform-tests/wpt'ın seyrek bir denetimli kopyasıdır; fetch/, streams/, FileAPI/, xhr/formdata/, dom/abort/, dom/events/ bölümlerini kapsar. Kapsamı genişletmek için herhangi bir *.any.js dosyasını upstream/<area>/'den tests/Wpt/fixtures/<category>/ içine kopyalayın. Çalıştırıcı, dosyayı sonraki çalıştırmada bulur; hatalar bin/wpt --verbose aracılığıyla kaydedilir.