Formattatore

Phasis fornisce un formattatore JavaScript nativo basato sul proprio parser. Ristampa il codice sorgente con una disposizione compatibile con prettier, interamente in PHP: senza Node.js, pacchetti di formattazione interpretati o processi esterni.

formatSource

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

Il punto di accesso con una sola chiamata su Phasis\Formatter\Formatter. $sourceType seleziona il linguaggio: script o module per JavaScript, json o css. JavaScript analizza il codice secondo l’obiettivo specificato, riassocia i commenti e stampa il risultato rispettando la larghezza configurata.

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"

Il codice sorgente non valido genera la stessa eccezione di Phasis\Exceptions\SyntaxError, con riga, colonna e offset.

FormatOptions

Le opzioni di impaginazione rispecchiano quelle di prettier 3.x e usano i valori predefiniti di prettier:

CSS

formatSource($css, 'css') formatta i fogli di stile con le regole di impaginazione di prettier: un selettore per riga negli elenchi di selettori, una dichiarazione per riga, spaziatura normalizzata per combinatori e valori, elenchi semplici di valori compattati quando possibile, valori separati da virgole disposti uno per riga per ombre e gradienti, argomenti delle funzioni mantenuti insieme o disposti su più righe, righe vuote e commenti conservati e preludi intatti per regole at sconosciute come Tailwind di @apply. I selettori composti lunghi vanno a capo in corrispondenza dei combinatori discendenti; gli argomenti troppo lunghi delle pseudoclassi vengono disposti su più righe all’interno delle parentesi.

JSON

formatSource($json, 'json') riutilizza il parser e i printer JavaScript con le regole JSON di prettier: le chiavi restano tra virgolette, le stringhe restano tra virgolette doppie indipendentemente da singleQuote, non vengono mai aggiunte virgole finali e i commenti // all’interno del documento vengono conservati.

Semantica dell’impaginazione

Il printer implementa il modello di documenti di prettier: i gruppi vengono disposti su una riga se rientrano nella larghezza di stampa, altrimenti vanno a capo; gli argomenti di chiamata restano vicini a un argomento finale di funzione o oggetto; le catene di membri vanno a capo prima di ogni punto quando superano la larghezza; gli oggetti scritti su più righe restano su più righe; tra le istruzioni viene conservata al massimo una riga vuota. Con opzioni corrispondenti, il formattatore produce un output identico byte per byte su codice reale già formattato con prettier; la suite di conformità lo verifica usando fixture generate direttamente da prettier.

Commenti

I commenti vengono raccolti durante la tokenizzazione (Parser::setCollectComments(true), esposti nel parser per gli strumenti) e riassociati all’albero come allegati iniziali, finali o isolati. I commenti di riga mantengono la propria riga, quelli finali sulla stessa riga restano associati alla loro istruzione, le righe vuote intorno ai commenti vengono conservate e i blocchi /** ... */ vengono rientrati allineando il margine *.

Garanzie

La suite di test verifica tre invarianti per ogni output formattato:

• L’output viene analizzato di nuovo in un programma equivalente (a parte le posizioni).
• Tutti i commenti dell’input sono presenti nell’output.
• La formattazione è idempotente: riformattare l’output non cambia nulla.

Prestazioni

La formattazione richiede il tempo del parser: i file reali vengono formattati in decine di millisecondi e il codice JavaScript scritto a mano in un progetto tipico viene formattato da cima a fondo in meno di un secondo in un singolo processo.