コンテンツへスキップ

互換性とアップグレード

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のリリース

Release 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は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()または@source inline("…")を使ってください。@sourceのパス形式はAPIでは無視され、CLIでは一部しか反映されません（下記参照）。

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

領域 現在の動作 問題
CLI @source パスとglobは適用されず、入力ファイルのディレクトリがスキャンされます。また、@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は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として渡したディレクトリ）を実行してください。コンパイラー状態キャッシュは自動的に無効になります。
  • 新機能： 作成者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()。