포매터

Phasis는 자체 파서를 기반으로 한 네이티브 JavaScript 포매터를 제공합니다. 소스를 prettier 호환 레이아웃 규칙에 따라 다시 출력하며, 전적으로 PHP에서 실행됩니다. Node.js도, 해석되는 포매터 번들도, 외부 프로세스도 필요하지 않습니다.

formatSource

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

Phasis\Formatter\Formatter의 단일 호출 진입점입니다. $sourceType로 언어를 선택합니다. JavaScript에는 script 또는 module를, 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의 스타일시트 레이아웃 규칙으로 스타일시트를 포맷합니다. 선택자 목록에서는 선택자마다 한 줄씩, 선언마다 한 줄씩 배치하고, 결합자와 값의 간격을 정규화합니다. 단순 값 목록은 줄 너비에 맞춰 채우고, 그림자와 그라디언트의 쉼표 목록은 항목마다 한 줄씩 배치합니다. 함수 인수는 모두 한 줄에 두거나 모두 여러 줄로 나누며, 빈 줄과 주석을 보존합니다. Tailwind의 @apply처럼 알 수 없는 at-rule의 전치부는 수정하지 않습니다. 긴 복합 선택자는 하위 선택자 결합자 앞에서 줄을 나누며, 너무 긴 의사 클래스 인수는 괄호 안에서 줄을 바꿉니다.

JSON

formatSource($json, 'json')는 JavaScript 파서와 프린터를 재사용하며 prettier의 JSON 규칙을 적용합니다. 키는 따옴표로 감싸고, singleQuote와 관계없이 문자열은 큰따옴표를 유지하며, 후행 쉼표는 사용하지 않습니다. 문서 내부의 // 주석도 보존됩니다.

레이아웃 규칙

프린터는 prettier 문서 모델을 구현합니다. 그룹이 출력 너비에 들어가면 한 줄로 펴고, 그렇지 않으면 줄을 나눕니다. 호출 인수는 뒤따르는 함수 또는 객체 인수와 붙여 배치하며, 멤버 체인이 줄을 넘으면 각 점 앞에서 줄을 나눕니다. 여러 줄로 작성된 객체는 여러 줄 형식을 유지하고, 문장 사이에는 빈 줄을 최대 하나까지 보존합니다. 옵션이 일치하는 prettier 포맷 입력은 실제 코드에서도 바이트 단위로 동일하게 출력됩니다. 적합성 테스트는 prettier 자체에서 생성한 픽스처로 이를 검증합니다.

주석

토큰화 중 주석을 수집하고(Parser::setCollectComments(true), 도구에서 사용할 수 있도록 파서에 노출됨) 트리에 선행, 후행 또는 독립 주석으로 다시 연결합니다. 줄 주석은 원래 줄에 유지되고, 같은 줄의 후행 주석은 해당 문장에 붙어 있으며, 주석 주변의 빈 줄도 보존됩니다. /** ... */ 블록은 들여쓰기를 다시 적용하고 * 여백을 맞춥니다.

보장 사항

테스트 스위트가 적용하는 다음 세 가지 불변 조건은 포맷된 모든 출력에서 성립합니다.

• 출력은 동등한 프로그램으로 다시 파싱됩니다(위치는 제외).
• 입력의 모든 주석이 출력에도 유지됩니다.
• 포맷은 멱등적입니다. 포맷된 출력을 다시 포맷해도 바뀌지 않습니다.

성능

포맷은 파서 속도로 실행됩니다. 실제 파일은 수십 밀리초 안에 포맷되며, 일반적인 프로젝트에서 직접 작성한 JavaScript도 단일 프로세스에서 전체 포맷에 1초가 채 걸리지 않습니다.