# Web API'leri

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](https://github.com/web-platform-tests/wpt) 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:

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

## fetch() örneği

```js
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

```js
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

```js
// 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.

```js
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ü](https://phasis.inline0.dev/tr/docs/api#event-loop) 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](https://phasis.inline0.dev/tr/docs/compatibility/limitations) 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](https://github.com/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.