# 호환성 및 업그레이드

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

## 요구 사항

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

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

## 추적하는 TailwindCSS 릴리스

릴리스 1.7.0는 **TailwindCSS v4.3.3**를 추적합니다. 업스트림 저장소는 `reference/tailwindcss`의 git 서브모듈로 고정하고, 해당 고정 체크아웃에서 테스트 스위트를 추출하며, 푸시할 때마다 4,427 테스트를 실행합니다([성능 및 테스트](https://tailwindphp.inline0.dev/ko/docs/advanced/performance) 참조). 포팅된 플러그인은 `@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()`](https://tailwindphp.inline0.dev/ko/docs/api#twextractcandidatesfromstrings) 또는 `@source inline("…")`를 사용하세요. `@source`의 경로 형식은 API에서 무시되며 CLI에서도 일부만 적용됩니다(아래 참고).

### 현재 릴리스의 알려진 문제

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