호환성 및 업그레이드

Markdown으로 보기 GitHub에서 수정 문서 위치 3843abd

이 페이지에서는 업그레이드하거나 정확한 출력을 기대할 때 알아야 할 내용을 정리합니다. 런타임 요구 사항, 포트가 따르는 TailwindCSS 릴리스, TailwindPHP이 TailwindCSS와 의도적으로 다른 부분, 각 릴리스의 참고 사항을 다룹니다. 전체 변경 이력은 CHANGELOG.md에 있습니다.

요구 사항

PHP 8.2 이상. 테스트 모음은 PHP 8.2, 8.3, 8.4에서 실행됩니다.
ctype 및 mbstring 확장. 컴파일러는 ctype_*와 mb_chr()를 호출합니다. 두 확장은 대부분의 PHP 빌드와 공식 Docker 이미지에 포함되어 있지만, 아직 composer.json에서 선언하지 않았습니다(#11). 따라서 이 확장 없이 빌드하면 패키지는 설치되지만 런타임에서 실패합니다.
선택 사항: pcntl 이 있으면 CLI의 --watch 모드가 SIGINT/SIGTERM에서 정상적으로 종료됩니다. 없어도 감시 모드는 작동합니다.

Node.js, FFI, 네이티브 바이너리는 사용하지 않습니다.

추적하는 TailwindCSS 릴리스

릴리스 1.7.0는 TailwindCSS v4.3.3를 추적합니다. 업스트림 저장소는 reference/tailwindcss의 git 서브모듈로 고정하고, 해당 고정 체크아웃에서 테스트 스위트를 추출하며, 푸시할 때마다 4,427 테스트를 실행합니다(성능 및 테스트 참조). 포팅된 플러그인은 @tailwindcss/typography과 @tailwindcss/forms을 따르고, 클래스 유틸리티는 clsx, tailwind-merge, CVA를 따릅니다. 각 항목은 같은 방식으로 고정됩니다.

TailwindCSS와의 알려진 차이점

직렬화 세부 사항

생성된 CSS는 참조 테스트 모음과 일치합니다. 직렬화 세부 사항 몇 가지는 TailwindCSS CLI가 출력하는 내용과 다르지만, 캐스케이드에는 영향을 주지 않습니다:

벤더 접두사: 참조 구현이 작성된 -webkit-* 줄과 생성된 줄을 모두 출력하는 경우, TailwindPHP는 한 줄만 출력합니다.
다운레벨된 의사 요소(::file-selector-button, ::-webkit-datetime-edit-*)는 의사 요소마다 규칙을 나누지 않고 작성된 선택자 목록에 그대로 둡니다.
작성된 작은따옴표 문자열은 큰따옴표로 정규화하지 않고 작은따옴표를 유지합니다('Segoe UI').
함께 나타나는 longhand 속성은 축약 속성으로 결합하지 않습니다(Tailwind 자체 출력에는 결합이 필요하지 않습니다).
.p-0는 padding: 0px를 유지합니다. 참조 구현은 CLI를 padding: 0로 출력하는데, 추출된 테스트 자료가 0px 형식으로 고정되어 있기 때문입니다. 축소기는 이를 0로 줄입니다.

포함되지 않는 항목

TailwindPHP는 CSS 컴파일러입니다. Tailwind 생태계의 편집기 도구(IntelliSense, 자동 완성, 클래스 정렬)와 소스 맵은 제공하지 않으므로 CLI에는 --map 옵션이 없습니다.

콘텐츠 스캔

tw::generate()와 TailwindCompiler::generate()은 class 및 className 속성에서만 클래스 이름을 읽습니다. PHP 또는 JavaScript 문자열에 들어 있는 클래스 이름에는 tw::extractCandidatesFromStrings() 또는 @source inline("…")를 사용하세요. @source의 경로 형식은 API에서 무시되며 CLI에서도 일부만 적용됩니다(아래 참고).

현재 릴리스의 알려진 문제

영역	현재 동작	문제
CLI `@source`	경로와 글로브가 적용되지 않습니다. 대신 입력 파일의 디렉터리를 스캔하며 `@source not`는 아무것도 제외하지 않습니다. CLI가 스캔하는 항목 참고	#8
CLI `--optimize`	`--minify`처럼 축소합니다	#9
CLI 긴 옵션	공백으로 구분된 `--input file.css`는 무시됩니다. `--input=file.css` 또는 `-i file.css`을 사용하세요	#13
플러그인 변형	`addVariant()`/`matchVariant()` 변형과 타이포그래피 요소 수정자(`prose-headings:` …)는 선택자 없이 컴파일됩니다	#10
`@apply` 믹스인	`@apply --my-mixin;`가 전달되지 않고 제거됩니다	#12
참조 가져오기	참조 가져오기가 유틸리티 가져오기보다 먼저 나오면 출력이 비어 있습니다. `@import "tailwindcss" reference`는 효과가 없습니다	#14

업그레이드 참고 사항

1.7.0

출력 바이트가 변경됩니다. 1.6.x와 비교하면 출력 바이트가 달라지지만 TailwindCSS v4.3.3 참조와 기능적으로 동일합니다. 눈에 띄는 변경 사항은 다음과 같습니다:
- 간격 배수: p-1는 padding: var(--spacing)를 출력하며 calc()는 출력하지 않습니다. 배수가 0이면 일반 0 길이 값을 출력합니다.
- 분수는 백분율로 변환됩니다: w-1/2는 width: 50%을 출력합니다.
- 색상: oklch()/oklab()의 명도는 백분율(oklch(62.3% .214 259.815))로 직렬화되고, white 및 black은 #fff 및 #000로 단축됩니다.
- CSS2 의사 요소는 콜론 하나로 직렬화됩니다(:before, :after, :first-letter, :first-line).
- 중첩된 @media/@supports/@container 규칙은 끝으로 이동하지 않고 소스 순서대로 제자리에 평탄화됩니다. 선언은 lightningcss의 순서에 따라 재정렬되고, 가려지는 중복 선언은 제거됩니다.
출력을 기준으로 한 캐시는 한 번 무효화됩니다. tw::generate()의 파일 캐시는 키에 TailwindPHP 버전을 포함하지 않으므로 업그레이드 후 tw::clearCache()(또는 cache로 전달한 디렉터리)를 실행하세요. 컴파일러 상태 캐시는 자동으로 무효화됩니다.
새 기능: 작성된 CSS의 @variant, @apply의 CSS 믹스인, @media reference 및 @import "…" reference, 함수형 @utility을 위한 전체 --value()/--modifier() 엔진, 더 엄격한 @utility 이름 검증, tw::compile()의 polyfills 옵션.

1.6.1

새 기능: container 유틸리티(width: 100%와 각 중단점마다 하나씩 추가되는 max-width).
조합된 --tw-* 변수(translate, scale, rotate, skew, 필터 등)가 이제 @property에 등록되어, 스타일시트에 해당 @property 규칙이 추가되고 translate-x-7 같은 변환이 브라우저에서 적용됩니다.

1.6.0

새 기능: 영구 컴파일러 상태 캐시(tw::compile() 및 TailwindCompiler에서 stateCacheFile, StateCache\compileCssCached()), 그리고 분리된 parseCssState()/finalizeCssState()/compileParsed() 함수. 기존 호출은 이전과 정확히 동일하게 동작합니다.

1.5.0

TailwindCompiler의 하위 클래스에서 generate() 또는 css()를 재정의하면 선택적 bool $minify = false 매개변수를 추가해야 합니다. PHP는 부모의 선택적 매개변수를 생략하는 재정의를 거부합니다.
축소 출력은 직렬화기에서 생성되므로 축소된 바이트는 1.4.x와 약간 다릅니다(축소 출력 기준 캐시는 한 번 무효화됩니다).
새 기능: 하나의 오래 실행되는 컴파일러에서 페이지별 CSS을 위한 generateExact() 및 cssExact().