Formator

Phasis oferă un formator nativ JavaScript, construit pe propriul parser. Reimprimă sursa folosind reguli de aranjare compatibile cu prettier, în întregime în PHP: fără Node.js, fără pachete de formatare interpretate și fără procese externe.

formatSource

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

Punctul de intrare cu un singur apel pentru Phasis\Formatter\Formatter. $sourceType selectează limbajul: script sau module pentru JavaScript, json sau css. JavaScript parsează conform scopului dat, reatașează comentariile și tipărește folosind lățimea configurată.

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"

Sursa nevalidă generează aceeași Phasis\Exceptions\SyntaxError ca parserul, cu linia, coloana și poziția.

FormatOptions

Opțiunile de aranjare reflectă 3.x din prettier și folosesc valorile implicite din prettier:

CSS

formatSource($css, 'css') formatează foile de stil conform aranjării pentru foi de stil din prettier: un selector pe linie în listele de selectori, o declarație pe linie, spațiere normalizată pentru combinatori și valori, liste simple de valori grupate cât încape, liste cu virgule pentru umbre și degradeuri cu câte un element pe linie, argumente ale funcțiilor păstrate împreună sau trecute toate pe linii separate, linii goale și comentarii păstrate, precum și preambuluri nemodificate pentru reguli at necunoscute, cum ar fi Tailwind din @apply. Selectorii compuși lungi se împart la combinatorii de descendență, iar argumentele prea lungi ale pseudo-claselor se încadrează în paranteze.

JSON

formatSource($json, 'json') reutilizează parserul și imprimantele JavaScript, împreună cu regulile JSON din prettier: cheile rămân între ghilimele, șirurile rămân între ghilimele duble indiferent de singleQuote, virgulele finale nu apar niciodată, iar comentariile // din document sunt păstrate.

Semantica aranjării

Imprimanta implementează modelul de documente prettier: grupurile sunt aplatizate când încap în lățimea de imprimare și se împart altfel, argumentele apelurilor se alipesc argumentului final de tip funcție sau obiect, lanțurile de membri se împart înaintea fiecărui punct când depășesc lățimea liniei, obiectele scrise pe mai multe linii rămân pe mai multe linii, iar între instrucțiuni se păstrează cel mult o linie goală. Pentru codul formatat de prettier cu opțiuni identice, formatarea produce aceiași octeți ca intrarea; suita de conformitate verifică exact acest lucru pe fixture-uri generate chiar de prettier.

Comentarii

Comentariile sunt colectate în timpul tokenizării (Parser::setCollectComments(true), expuse de parser pentru instrumente) și reatașate arborelui ca atașamente anterioare, ulterioare sau suspendate. Comentariile pe linie își păstrează liniile, comentariile de la finalul aceleiași linii rămân pe instrucțiunea lor, liniile goale din jurul comentariilor sunt păstrate, iar blocurile /** ... */ sunt reindentate cu marginea lor * aliniată.

Garanții

Trei invariabile sunt valabile pentru fiecare rezultat formatat, verificate de suita de teste:

• Rezultatul este parsată într-un program echivalent (cu excepția pozițiilor).
• Fiecare comentariu din intrare este păstrat în rezultat.
• Formatarea este idempotentă: reformatarea rezultatului formatat nu schimbă nimic.

Performanță

Formatarea rulează cu viteza parserului: fișierele reale se formatează în zeci de milisecunde, iar un JavaScript obișnuit, scris manual pentru un proiect, se formatează cap-coadă în mult sub o secundă într-un singur proces.