Formázó

A Phasis saját parserére épülő natív JavaScript formázót biztosít. A forráskódot prettier-kompatibilis elrendezési szabályok szerint írja újra, teljes egészében PHP nyelven: nincs szükség Node.js-re, értelmezett formázócsomagokra vagy külső folyamatokra.

formatSource

public static function formatSource(
    string $source,
    string $sourceType = 'script',
    ?FormatOptions $options = null,
): string

Az egyhívásos belépési pont a Phasis\Formatter\Formatter része. A $sourceType választja ki a nyelvet: script vagy module a JavaScript esetén, illetve json vagy css. A JavaScript a megadott cél szerint feldolgozza a forrást, visszailleszti a megjegyzéseket, majd a beállított sorhosszhoz igazítva kiírja.

use Phasis\Formatter\Formatter;
use Phasis\Formatter\FormatOptions;

$formatted = Formatter::formatSource(
    "const a={x:1,y:2};",
    'script',
    new FormatOptions(useTabs: true, singleQuote: true),
);
// "const a = { x: 1, y: 2 };\n"

Érvénytelen forrás esetén ugyanaz a Phasis\Exceptions\SyntaxError hiba keletkezik, mint a parsernél, sor-, oszlop- és eltolási adatokkal.

FormatOptions

Az elrendezési beállítások a prettier 3.x beállításait követik, alapértelmezésük pedig megegyezik a prettier alapértékeivel:

CSS

A formatSource($css, 'css') a stíluslapokat a prettier stílusában formázza: szelektorlistánként egy szelektor soronként, deklarációnként egy sor, egységesített kombinátor- és értékközök, kitöltött egyszerű értéklisták, árnyékok és színátmenetek vesszővel tagolt elemei külön soronként, függvényargumentumok csak teljes egészükben maradnak egy sorban vagy törnek több sorba, megőrzött üres sorok és megjegyzések, az ismeretlen at-szabályok, például a Tailwind @apply előtagjai pedig változatlanok. A hosszú összetett szelektorok leszármazott-kombinátoroknál törnek, a túl hosszú pszeudoosztály-argumentumok pedig a zárójeleken belül tördelődnek.

JSON

A formatSource($json, 'json') a JavaScript parserét és kiíróit használja újra a prettier JSON-szabályaival: a kulcsok idézőjelben maradnak, a karakterláncok az singleQuote értékétől függetlenül dupla idézőjelet kapnak, a záró vesszők soha nem jelennek meg, és a dokumentumon belüli // megjegyzések megmaradnak.

Elrendezési szabályok

A kiíró a prettier dokumentummodelljét valósítja meg: a csoportok egy sorba rendeződnek, ha beleférnek a megadott sorhosszba, különben sortörést kapnak; a hívási argumentumok közvetlenül a záró függvény vagy objektumargumentumhoz kerülnek; a túl hosszú tagláncok minden pont előtt sort törnek; a több sorban megírt objektumok több sorosak maradnak; az utasítások között pedig legfeljebb egy üres sor marad meg. Az azonos beállításokkal, prettier formázású bemeneten a formázó valós kódon bájtról bájtra azonos kimenetet ad; ezt a megfelelőségi tesztcsomag a prettierrel generált tesztadatokkal ellenőrzi.

Megjegyzések

A megjegyzések a tokenizálás során gyűlnek össze (Parser::setCollectComments(true), az eszközök számára elérhetők a parseren), majd a fához vezető, követő vagy önálló megjegyzésként kerülnek vissza. A sorvégi megjegyzések a saját sorukban maradnak, az ugyanazon a soron lévő záró megjegyzések az utasításukhoz tapadnak, a megjegyzések körüli üres sorok megmaradnak, a /** ... */ blokkok pedig új behúzást kapnak, igazított * margóval.

Garanciák

A tesztcsomag három invariánst tartat be minden formázott kimeneten:

• A kimenet azonos értelmű programmá parse-olható (a helyadatokat nem számítva).
• A bemenet összes megjegyzése megmarad a kimenetben.
• A formázás idempotens: a formázott kimenet ismételt formázása nem változtat rajta.

Teljesítmény

A formázás a parser sebességével fut: valós fájlok néhány tíz milliszekundum alatt formázódnak, egy tipikus projekt saját készítésű JavaScript fájljai pedig egyetlen folyamatban, a teljes feldolgozással együtt, jóval egy másodperc alatt elkészülnek.