Formatter

Phasis leverer en indbygget JavaScript-formaterer bygget på sin egen parser. Den udskriver kildeteksten igen med layoutsemantik, der er kompatibel med prettier, helt i PHP: ingen Node.js, ingen fortolkede formatter-bundles og ingen eksterne processer.

formatSource

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

Indgangspunktet med ét kald på Phasis\Formatter\Formatter. $sourceType vælger sproget: script eller module for JavaScript, json eller css. JavaScript parser ud fra det angivne mål, tilknytter kommentarerne igen og udskriver efter den konfigurerede linjebredde.

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"

Ugyldig kildekode udløser samme Phasis\Exceptions\SyntaxError som parseren, med linje, kolonne og position.

FormatOptions

Layoutindstillingerne svarer til prettier 3.x og bruger prettiers standardindstillinger:

CSS

formatSource($css, 'css') formaterer stylesheets med prettiers stylesheet-layout: én selector pr. linje i selectorlister, én deklaration pr. linje, normaliseret afstand omkring kombinatorer og værdier, simple værdilister pakket så vidt muligt, kommaseparerede lister med skygger og gradienter én pr. linje, funktionsargumenter enten samlet eller opdelt, bevarede tomme linjer og kommentarer samt uændrede præambler for ukendte at-regler som Tailwinds @apply. Lange sammensatte selectorer brydes ved descendant-kombinatorer, og for lange argumenter i pseudoklasser ombrydes inden for parenteserne.

JSON

formatSource($json, 'json') genbruger parseren og printerne fra JavaScript med prettiers JSON-regler: nøgler forbliver citerede, strenge forbliver dobbeltciterede uanset singleQuote, afsluttende kommaer forekommer aldrig, og //-kommentarer i dokumentet bevares.

Layoutsemantik

Printeren implementerer prettiers dokumentmodel: grupper flades ud, når de passer inden for udskriftsbredden, og brydes ellers; funktionskalds argumenter placeres tæt op ad et afsluttende funktions- eller objektargument; medlemskæder brydes før hvert punktum, når de bliver for lange til linjen; objekter, der er skrevet over flere linjer, forbliver på flere linjer; og højst én tom linje bevares mellem statements. Ved input formateret af prettier med matchende indstillinger er formatterens bytes identiske for kode fra den virkelige verden; dens overensstemmelsestest kontrollerer netop dette mod fixtures genereret af prettier selv.

Kommentarer

Kommentarer indsamles under tokenisering (Parser::setCollectComments(true), tilgængelige via parseren til værktøjer) og knyttes igen til træet som indledende, afsluttende eller fritstående kommentarer. Linjekommentarer bliver på deres egne linjer, afsluttende kommentarer på samme linje forbliver ved deres statement, tomme linjer omkring kommentarer bevares, og /** ... */-blokke indrykkes igen, så deres *-margin flugter.

Garantier

Tre invariants gælder for hvert formateret output og håndhæves af testsuiten:

• Outputtet kan parses igen til et tilsvarende program (bortset fra placeringer).
• Alle kommentarer i input bevares i outputtet.
• Formateringen er idempotent: Formatering af formateret output ændrer intet.

Ydeevne

Formatering foregår med parserhastighed: filer fra den virkelige verden formateres på få tiendedele millisekunder, og et typisk projekts håndskrevne JavaScript formateres fra ende til anden på langt under et sekund i én proces.