# 互換性とアップグレード

このページでは、アップグレードや出力の厳密な一致を求める際に知っておくべきことをまとめています。実行要件、移植版が追従する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のリリース

Release 1.7.0は**TailwindCSS v4.3.3**を追跡します。上流リポジトリは`reference/tailwindcss`内のgitサブモジュールとして固定され、その固定済みチェックアウトからテストスイートを抽出します。4,427のテストはプッシュのたびに実行されます（[パフォーマンスとテスト](https://tailwindphp.inline0.dev/ja/docs/advanced/performance)を参照）。移植されたプラグインは`@tailwindcss/typography`と`@tailwindcss/forms`に準拠し、クラスユーティリティはclsx、tailwind-merge、CVAに準拠します。いずれも同じ方法でバージョンを固定しています。

## TailwindCSSとの既知の差異

### シリアライズの詳細

生成されるCSSは参照テストスイートと一致します。TailwindCSSのCLIが出力する内容とはシリアライズの細部が若干異なりますが、カスケードに影響するものはありません。

- ベンダープレフィックス：参照実装が記述された`-webkit-*`行と生成行の両方を出力する箇所で、TailwindPHPは1行だけ出力します。
- ダウンレベル化された疑似要素（`::file-selector-button`、`::-webkit-datetime-edit-*`）は、疑似要素ごとにルールへ分割せず、記述されたセレクターリスト内に残ります。
- 記述されたシングルクォートの文字列はシングルクォートのまま（`'Segoe UI'`）になり、ダブルクォートには正規化されません。
- 同時に存在するロングハンドはショートハンドにまとめられません（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/ja/docs/api#twextractcandidatesfromstrings)または`@source inline("…")`を使ってください。`@source`のパス形式はAPIでは無視され、CLIでは一部しか反映されません（下記参照）。

### 現行リリースの既知の問題

| 領域 | 現在の動作 | 問題 |
|---|---|---|
| CLI `@source` | パスとglobは適用されず、入力ファイルのディレクトリがスキャンされます。また、`@source not`は何も除外しません。[CLIがスキャンする対象](https://tailwindphp.inline0.dev/ja/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`は`calc()`の代わりに`padding: var(--spacing)`を出力し、倍率`0`は単位のないゼロを出力します。
  - 分数はパーセンテージに変換されます：`w-1/2`は`width: 50%`を出力します。
  - 色：`oklch()`/`oklab()`の明度はパーセンテージとしてシリアライズされ（`oklch(62.3% .214 259.815)`）、`white`と`black`はそれぞれ`#fff`と`#000`に短縮されます。
  - CSS2の疑似要素はコロン1つでシリアライズされます（`:before`、`:after`、`:first-letter`、`:first-line`）。
  - ネストされた`@media`/`@supports`/`@container`ルールは末尾へ移動せず、ソース順のままその場でフラット化されます。宣言はlightningcssの順序に並べ替えられ、上書きされた重複宣言は削除されます。
- **出力をキーにするキャッシュは一度無効になります。** `tw::generate()`のファイルキャッシュではTailwindPHPのバージョンがキーに含まれないため、アップグレード後に`tw::clearCache()`（または`cache`として渡したディレクトリ）を実行してください。[コンパイラー状態キャッシュ](https://tailwindphp.inline0.dev/ja/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%`とブレークポイントごとに1つの`max-width`）。
- 合成された`--tw-*`変数（translate、scale、rotate、skew、filtersなど）が`@property`に登録されるようになりました。これにより、スタイルシートに`@property`ルールが追加され、`translate-x-7`などの変換がブラウザーで有効になります。

### 1.6.0

- **新機能：** 永続的なコンパイラー状態キャッシュ（`tw::compile()`と`TailwindCompiler`での`stateCacheFile`、`StateCache\compileCssCached()`）、および分割された`parseCssState()`/`finalizeCssState()`/`compileParsed()`関数。既存の呼び出しの動作は変わりません。

### 1.5.0

- `generate()`または`css()`をオーバーライドする`TailwindCompiler`のサブクラスは、任意の`bool $minify = false`パラメーターを追加する必要があります。PHPは、親の任意パラメーターを省略するオーバーライドを拒否します。
- ミニファイ済み出力はシリアライザーから生成されるため、ミニファイ後のバイト列は1.4.xと若干異なります（ミニファイ済み出力をキーにするキャッシュは一度無効になります）。
- **新機能：** 長期間使う1つのコンパイラーからページ単位のCSSを得るための`generateExact()`と`cssExact()`。