Formater

Phasis udostępnia natywny formatter JavaScript oparty na własnym parserze. Ponownie zapisuje kod źródłowy z semantyką układu zgodną z prettier, całkowicie w PHP: bez Node.js, interpretowanych pakietów formattera ani procesów zewnętrznych.

formatSource

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

Punkt wejścia wykonujący jedno wywołanie na Phasis\Formatter\Formatter. $sourceType wybiera język: script lub module dla JavaScript, json lub css. JavaScript parsuje kod zgodnie z podanym celem, ponownie dołącza komentarze i drukuje kod z uwzględnieniem skonfigurowanej szerokości wydruku.

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"

Nieprawidłowy kod źródłowy powoduje ten sam Phasis\Exceptions\SyntaxError co parser, wraz z numerem wiersza, kolumny i przesunięciem.

FormatOptions

Opcje układu odpowiadają 3.x prettier i domyślnie przyjmują ustawienia prettier:

CSS

formatSource($css, 'css') formatuje arkusze stylów zgodnie z układem arkuszy stylów prettier: jeden selektor w wierszu na listach selektorów, jedna deklaracja w wierszu, ujednolicone odstępy wokół kombinatorów i wartości, proste listy wartości wypełniające wiersz, listy rozdzielane przecinkami dla cieni i gradientów zapisywane po jednym elemencie w wierszu, argumenty funkcji formatowane w całości albo wcale, zachowane puste wiersze i komentarze oraz nietknięte preambuły nieznanych reguł at, takich jak Tailwind z @apply. Długie złożone selektory są łamane przy kombinatorach potomka, a zbyt długie argumenty pseudoklas zawijane wewnątrz nawiasów.

JSON

formatSource($json, 'json') ponownie wykorzystuje parser i drukarki JavaScript wraz z regułami JSON prettier: klucze pozostają ujęte w cudzysłowy, ciągi pozostają ujęte w podwójne cudzysłowy niezależnie od singleQuote, przecinki końcowe nigdy się nie pojawiają, a komentarze // wewnątrz dokumentu są zachowywane.

Semantyka układu

Drukarka implementuje model dokumentu prettier: grupy są rozwijane do jednego wiersza, jeśli mieszczą się w szerokości wydruku, w przeciwnym razie są łamane; argumenty wywołań przylegają do końcowego argumentu funkcji lub obiektu; łańcuchy dostępu do elementów są łamane przed każdą kropką, gdy przekraczają szerokość wiersza; obiekty zapisane w wielu wierszach pozostają wielowierszowe; między instrukcjami zachowywany jest co najwyżej jeden pusty wiersz. Dla kodu sformatowanego przez prettier z tymi samymi opcjami formatter daje identyczne bajtowo wyniki dla rzeczywistego kodu; jego zestaw testów zgodności dokładnie to sprawdza na podstawie przykładów wygenerowanych przez samo prettier.

Komentarze

Komentarze są zbierane podczas tokenizacji (Parser::setCollectComments(true), udostępniane w parserze narzędziom) i ponownie dołączane do drzewa jako elementy poprzedzające, końcowe lub luźne. Komentarze w wierszu zachowują własne wiersze, komentarze końcowe w tym samym wierszu pozostają przy swojej instrukcji, puste wiersze wokół komentarzy są zachowywane, a bloki /** ... */ są ponownie wcięte tak, by ich margines * był wyrównany.

Gwarancje

Zestaw testów wymusza trzy niezmienniki dla każdego sformatowanego wyniku:

• Wynik można ponownie sparsować do równoważnego programu (pomijając lokalizacje).
• Wszystkie komentarze z wejścia są zachowane w wyniku.
• Formatowanie jest idempotentne: ponowne formatowanie sformatowanego wyniku niczego nie zmienia.

Wydajność

Formatowanie działa z szybkością parsera: rzeczywiste pliki są formatowane w dziesiątki milisekund, a typowy, napisany ręcznie JavaScript projektu formatuje się od początku do końca w znacznie mniej niż sekundę w jednym procesie.