Форматувальник

Phasis постачає вбудований форматувальник JavaScript, побудований на власному парсері. Він виводить вихідний код із правилами розмітки, сумісними з prettier, повністю в PHP: без Node.js, інтерпретованих пакетів форматувальника та зовнішніх процесів.

formatSource

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

Універсальна точка входу Phasis\Formatter\Formatter для одного виклику. $sourceType задає мову: script або module для JavaScript, json чи css. JavaScript виконує розбір відповідно до заданої мети, повертає коментарі на місце та друкує результат із заданою шириною рядка.

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"

Для некоректного вихідного коду виникає та сама помилка Phasis\Exceptions\SyntaxError, що й у парсера, із зазначенням рядка, стовпця та зміщення.

FormatOptions

Параметри розмітки відповідають prettier 3.x і за замовчуванням використовують стандартні значення prettier:

CSS

formatSource($css, 'css') форматує таблиці стилів за правилами розмітки таблиць стилів prettier: один селектор на рядок у списках селекторів, одне оголошення на рядок, нормалізовані пробіли навколо комбінаторів і значень, компактні списки простих значень, списки тіней і градієнтів із комою після кожного елемента на окремому рядку, аргументи функцій або всі в одному рядку, або кожен на окремому, збереження порожніх рядків і коментарів, а також незмінені прелюдії невідомих at-правил, як-от Tailwind @apply. Довгі складені селектори розбиваються на комбінаторах нащадків, а надто довгі аргументи псевдокласів переносяться всередині дужок.

JSON

formatSource($json, 'json') повторно використовує парсер і принтери JavaScript із правилами JSON від prettier: ключі залишаються в лапках, рядки завжди беруться в подвійні лапки незалежно від singleQuote, кінцевих ком немає, а коментарі // усередині документа зберігаються.

Правила розмітки

Принтер реалізує модель документа prettier: групи згортаються, якщо вміщуються у ширину друку, інакше переносяться; аргументи виклику прилягають до кінцевого аргументу-функції або об’єкта; ланцюжки властивостей розриваються перед кожною крапкою, якщо виходять за межі рядка; об’єкти, записані в кількох рядках, залишаються багаторядковими; між інструкціями зберігається не більш ніж один порожній рядок. Для коду, відформатованого prettier з відповідними параметрами, форматувальник створює байт-у-байт ідентичний результат на реальному коді; набір перевірок відповідності підтверджує це за допомогою зразків, згенерованих самим prettier.

Коментарі

Коментарі збираються під час токенізації (Parser::setCollectComments(true), доступні в парсері для інструментів) і повертаються до дерева як початкові, кінцеві або висячі вкладення. Коментарі рядка залишаються на своїх рядках, кінцеві коментарі в тому самому рядку залишаються при своїй інструкції, порожні рядки навколо коментарів зберігаються, а блоки /** ... */ отримують відступи, вирівняні за полем *.

Гарантії

Для кожного відформатованого результату виконуються три інваріанти, перевірені набором тестів:

• Результат повторно розбирається в еквівалентну програму (без урахування розташування).
• Усі коментарі з вхідного коду зберігаються у результаті.
• Форматування ідемпотентне: повторне форматування результату нічого не змінює.

Продуктивність

Форматування працює зі швидкістю парсера: файли з реального світу форматуються за десятки мілісекунд, а типовий написаний вручну JavaScript у звичайному проєкті повністю форматується за значно менше ніж секунду в одному процесі.