# Wprowadzenie
Phasis to czysty, oparty na PHP silnik JavaScript. Analizuje leksykalnie, parsuje i wykonuje ECMAScript w procesie hosta PHP — bez `exec('node …')`, FFI ani niestandardowego rozszerzenia binarnego. Wymaga trzech standardowych rozszerzeń PHP: `ext-mbstring`, `ext-bcmath` i `ext-curl` (domyślnego transportu `fetch()`). `ext-intl` i `ext-openssl` są opcjonalne. Informacje o kompilacjach bez `bcmath` znajdziesz w sekcji [Pierwsze kroki](https://phasis.inline0.dev/pl/docs/getting-started).

- **Możliwość osadzania** — dodaj środowisko uruchomieniowe JS do dowolnej aplikacji PHP, frameworka lub narzędzia CLI za pomocą klasy `Phasis\Engine`.
- **Zgodność ze specyfikacją** — przechodzi oficjalny zestaw testów test262 w 100 %, wszystkie kategorie, bez pominięć.
- **Interfejsy Web API** — pełny **Web Platform Pack** (URL, TextEncoder/Decoder, atob/btoa, structuredClone, performance, DOMException), pełny **Fetch Pack** (fetch, Request, Response, Headers, Body, AbortController/Signal, Blob, File, FormData, EventTarget, pełne strumienie WHATWG, navigator), a także `crypto` + `SubtleCrypto`, `WebSocket`, `XMLHttpRequest` i rzeczywista pętla zdarzeń. Zaimplementowano 100 % zaimportowanych testów Web Platform Tests.
- **Nowoczesny zakres funkcji** — funkcje strzałkowe, klasy, async/await, Promises, generatory, Symbol, BigInt, Proxy, Reflect, Temporal, Intl, TypedArrays, pełna obsługa modułów.
- **Współdziałanie PHP↔JS** — przekazuj skalarne wartości PHP i tablice do JS (tablice są kopiowane), wiąż domknięcia PHP jako funkcje JS i wywołuj funkcje JS z poziomu PHP. Obiektów PHP nie można jeszcze współdzielić z JS; zobacz [Współdzielone obiekty](https://phasis.inline0.dev/pl/docs/interop/shared-objects).

## Dlaczego powstał Phasis

Aplikacje PHP, które muszą uruchamiać dostarczony przez użytkownika kod JavaScript — silniki szablonów, nakładki SSR frontendu, reguły walidacji danych, piaskownice treści, bezgłowe narzędzia do testów — zwykle uruchamiają zewnętrznie Node.js albo pomijają tę funkcję. Oba rozwiązania zwiększają złożoność operacyjną: drugie środowisko uruchomieniowe, granica serializacji, sieć potoków procesów potomnych oraz trudne wdrażanie na współdzielonym hostingu.

Phasis wypełnia tę lukę. Kod PHP może analizować leksykalnie, parsować i wykonywać JavaScript, korzystając wyłącznie z PHP 8.2+ oraz `mbstring`, `bcmath` i `curl`. Silnik jest dostarczany jako pakiet Composer i udostępnia niewielki, jednolity interfejs API.

## Funkcje

- Implementuje pełną bibliotekę standardową ECMAScript: `Array`, `String`, `Object`, `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `Promise`, `Proxy`, `Reflect`, `Symbol`, `BigInt`, `TypedArray`, `Temporal`, `Intl`, generatory, iteratory asynchroniczne, moduły.
- Dostarcza interfejsy API **Web Platform**, które biblioteki JS często sprawdzają w pierwszej kolejności: `URL`, `URLSearchParams`, `TextEncoder`/`TextDecoder`, `atob`/`btoa`, `structuredClone`, `performance`, `DOMException`. Pełny zakres znajdziesz w sekcji [Interfejsy Web API](https://phasis.inline0.dev/pl/docs/compatibility/web-apis).
- Dostarcza **`fetch`** z pełnym zestawem Fetch — `Request`, `Response`, `Headers`, odbiorcy treści, `AbortController`/`AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`/`Event` oraz pełnymi strumieniami WHATWG (`ReadableStream`, `WritableStream`, `TransformStream`, BYOB, strategie kolejkowania). Rzeczywiste HTTP działa od razu dzięki PHP's `ext-curl`.
- Dostarcza **`crypto`** i pełny `SubtleCrypto` (rodzina SHA, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2), **`WebSocket`** (RFC 6455 i wymienny transport) oraz **`XMLHttpRequest`** (oparty na tym samym transporcie Fetch).
- Dostarcza prawdziwą **pętlę zdarzeń**: `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask` oraz `AsyncContext` etapu 3 do przekazywania wartości między granicami operacji asynchronicznych.
- Obsługuje nowoczesną składnię — destrukturyzację, spread/rest, właściwości obliczane, opcjonalne łańcuchowanie, operator koalescencji nullish, literały szablonowe, szablony z tagiem, klasy (z polami prywatnymi, blokami statycznymi i dekoratorami), await na najwyższym poziomie.
- Konwertuje wartości na granicy PHP↔JS. Skalary i tablice są kopiowane do środowiska, wywoływalne elementy PHP stają się funkcjami JS, a wyniki JS wracają jako skalary i tablice PHP. Dokładne reguły opisano w sekcji [Konwersja wartości](https://phasis.inline0.dev/pl/docs/interop/values).
- Działa pod kontrolą hosta. Host zarządza transportem `fetch` i punktami kontrolnymi polityk, pętla zdarzeń działa w czasie wirtualnym, a stały limit stosu wywołań zatrzymuje niekontrolowaną rekurencję. Dostępny jest limit liczby iteracji pętli, ale nie jest jeszcze egzekwowany dla pętli uruchamianych przez maszynę wirtualną kodu bajtowego; nie ma też limitów długości ciągów, wyjścia ani czasu rzeczywistego. Zobacz [API: setLimit](https://phasis.inline0.dev/pl/docs/api#setlimit).
- Jest weryfikowany względem Node.js (V8). CI uruchamia zestawy testów jednostkowych i testów z użyciem wzorca po każdym wypchnięciu zmian do `main` oraz przy każdym pull requeście, a także testy Web Platform Tests i popularnych pakietów przy zmianach kodu źródłowego silnika; pełna macierz test262 jest uruchamiana ręcznie, a jej migawka trafia do `COMPAT.md`. Zobacz [Zgodność](https://phasis.inline0.dev/pl/docs/compatibility).

## Czym nie jest

Phasis nie jest kompilatorem JIT. To interpreter przechodzący po drzewie z opportunistyczną maszyną wirtualną kodu bajtowego. W zadaniach ograniczonych szybkością wysyłania oczekuj czasu wykonania ~100× dłuższego niż w V8. Kompromisem są zerowe zależności, czysty PHP i wykonanie kontrolowane przez hosta — idealne do osadzania JavaScript w aplikacjach PHP, gdzie poprawność i izolacja są ważniejsze niż surowa przepustowość.

## Od czego zacząć

- [Pierwsze kroki](https://phasis.inline0.dev/pl/docs/getting-started) — instalacja i uruchomienie pierwszego skryptu.
- [CLI](https://phasis.inline0.dev/pl/docs/cli) — `bin/phasis` do uruchamiania plików, ewaluacji kodu źródłowego i zrzucania AST.
- [API](https://phasis.inline0.dev/pl/docs/api) — osadź `Phasis\Engine` w swojej aplikacji PHP.
- [Współdziałanie](https://phasis.inline0.dev/pl/docs/interop) — przekazywanie wartości i funkcji wywoływalnych PHP do JavaScript.
- [Zgodność](https://phasis.inline0.dev/pl/docs/compatibility) — pokrycie test262 i obsługiwane funkcje.
- [Parser](https://phasis.inline0.dev/pl/docs/parser) — parsowanie JavaScript do typowanego AST lub ESTree bez wykonywania kodu.
- [Formater](https://phasis.inline0.dev/pl/docs/formatter) — formatowanie JavaScript, JSON i CSS z układem zgodnym z prettier.
- [Zaawansowane](https://phasis.inline0.dev/pl/docs/advanced) — architektura, maszyna wirtualna kodu bajtowego, testy wydajności i model testowania z użyciem wzorca.