Formatter

Phasis levert een native JavaScript-formatter, gebouwd op zijn eigen parser. Die drukt broncode opnieuw af volgens indelingssemantiek die compatibel is met prettier, volledig in PHP: geen Node.js, geen geïnterpreteerde formatterbundels en geen externe processen.

formatSource

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

Het ingangspunt met één aanroep op Phasis\Formatter\Formatter. $sourceType kiest de taal: script of module voor JavaScript, json of css. JavaScript parseert volgens het opgegeven doel, koppelt de opmerkingen er opnieuw aan en drukt de code af binnen de ingestelde afdrukbreedte.

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"

Ongeldige broncode geeft dezelfde Phasis\Exceptions\SyntaxError als de parser, met regel, kolom en offset.

FormatOptions

De indelingsopties komen overeen met die van prettier 3.x en gebruiken standaard de standaardwaarden van prettier:

CSS

formatSource($css, 'css') formatteert stylesheets met de stylesheet-indeling van prettier: één selector per regel in selectielijsten, één declaratie per regel, genormaliseerde spatiëring rond combinators en waarden, eenvoudige waardelijsten compact gevuld, komma's in lijsten met schaduwen en verlopen op aparte regels, functieargumenten alles-of-niets, lege regels en opmerkingen behouden, en preludes voor onbekende at-regels, zoals Tailwind's @apply, ongemoeid gelaten. Lange samengestelde selectors worden afgebroken bij afstammingscombinators en te lange argumenten van pseudo-klassen lopen binnen hun haakjes door op meerdere regels.

JSON

formatSource($json, 'json') hergebruikt de parser en printers van JavaScript met de JSON-regels van prettier: sleutels blijven tussen aanhalingstekens staan, strings blijven dubbel geciteerd ongeacht singleQuote, afsluitende komma's komen nooit voor en //-opmerkingen binnen het document blijven behouden.

Indelingssemantiek

De printer implementeert het documentmodel van prettier: groepen worden samengevouwen als ze binnen de afdrukbreedte passen en anders afgebroken; aanroepargumenten sluiten aan bij een afsluitend functie- of objectargument; ketens van leden worden vóór elke punt afgebroken als ze de regel te lang maken; objecten die over meerdere regels zijn geschreven, blijven meerregelig; en er blijft maximaal één lege regel tussen statements behouden. Bij invoer die met prettier is opgemaakt en dezelfde opties gebruikt, is de formatter byte-identiek voor echte code; de conformiteitstest controleert dit precies aan de hand van testbestanden die door prettier zelf zijn gegenereerd.

Opmerkingen

Opmerkingen worden tijdens het tokeniseren verzameld (Parser::setCollectComments(true), beschikbaar op de parser voor tooling) en opnieuw aan de boom gekoppeld als vooraanstaande, afsluitende of losse toevoegingen. Regels met opmerkingen behouden hun eigen regels, afsluitende opmerkingen op dezelfde regel blijven bij hun statement, lege regels rond opmerkingen blijven behouden en blokken met /** ... */ krijgen opnieuw ingesprongen regels met de *-marge uitgelijnd.

Garanties

Voor elke opgemaakte uitvoer gelden drie invarianten, afgedwongen door de testsuite:

• De uitvoer kan opnieuw worden geparseerd tot een gelijkwaardig programma (locaties daargelaten).
• Elke opmerking uit de invoer blijft behouden in de uitvoer.
• De opmaak is idempotent: opgemaakte uitvoer formatteren verandert niets.

Prestaties

Formatteren gaat zo snel als parsen: echte bestanden worden in tientallen milliseconden opgemaakt en de handgeschreven JavaScript van een typisch project wordt in één proces in ruim minder dan een seconde volledig opgemaakt.