# API

静的機能全体は1つのクラスにあります: `TailwindPHP\tw`（内部`Tailwind`クラスの別名）。すべてのメソッドを静的に呼び出せます。また、検査メソッド（`properties`、`computedProperties`、`value`、`computedValue`）は、ページ下部で説明する[入力形式](#input-formats)をすべて受け付けます。

同じCSS設定で処理を繰り返す場合は、[`tw::compile()`](#twcompile)を一度呼び出し、返された[`TailwindCompiler`](#tailwindcompiler-instance-methods)を再利用してください。

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="flex items-center p-4 bg-blue-500">');
```

## tw::generate()

```php
public static function generate(string|array $input, string $css = '@import "tailwindcss";'): string
```

コンテンツを解析し、クラス候補を抽出して、生成されたCSSを返します。デフォルトの`$css`は`@import "tailwindcss";`で、theme、preflight、utilitiesを読み込みます。**戻り値** `string`。

```php
use TailwindPHP\tw;

// String input
$css = tw::generate('<div class="flex p-4">');

// String with custom CSS
$css = tw::generate('<div class="flex bg-brand">', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

// Array input with options
$css = tw::generate([
    'content' => '<div class="flex p-4">',
    'css' => '@import "tailwindcss";',
    'minify' => true,
]);
```

配列形式で指定できるキー:

| キー | 型 | 用途 |
|---|---|---|
| `content` | `string` | クラス候補をスキャンするコンテンツ（必須） |
| `css` | `string` | Tailwindディレクティブを含む入力CSS（デフォルト`@import "tailwindcss";`） |
| `minify` | `bool` | 出力をミニファイ（デフォルト`false`） |
| `importPaths` | `string \| array \| callable \| null` | ファイルシステムからCSSを読み込み、`@import`解決をすべて行う — [CSSのインポート](https://tailwindphp.inline0.dev/ja/docs/usage/imports)を参照 |
| `cache` | `bool \| string` | ファイルキャッシュを有効化 — [キャッシュ](#caching)を参照 |
| `cacheTtl` | `int` | キャッシュの有効期間（秒） |

## tw::compile()

```php
public static function compile(string $css = '@import "tailwindcss";', array $options = []): TailwindCompiler
```

指定されたCSSに紐づく再利用可能な`TailwindCompiler`を作成します。解析とデザインシステムの構築は一度だけ行われるため、異なるコンテンツ文字列からCSSを多数生成する場合に効率的です。`generate()`を使うと複数回の呼び出しで1つのスタイルシートに蓄積でき、独立したページごとの出力には[`generateExact()`](#accumulating-vs-exact-generation)を使えます。**戻り値** `TailwindCompiler`。

```php
use TailwindPHP\tw;

// Default Tailwind
$compiler = tw::compile();

// Custom CSS
$compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

$css = $compiler->generate('<div class="flex p-4 bg-brand">');
```

`$options`配列で指定できる項目:

| オプション | 型 | 用途 |
|---|---|---|
| `stateCacheFile` | `string` | リクエストやプロセスをまたいでコンパイラーの構築状態を保持するPHPファイルのパス — [コンパイラー状態のキャッシュ](https://tailwindphp.inline0.dev/ja/docs/advanced/caching#compiler-state-cache)を参照 |
| `polyfills` | `int` | 出力するフォールバックを`TailwindPHP\POLYFILL_AT_PROPERTY`のビットマスクで指定します（`@property`変数の`@layer properties`デフォルト）および`TailwindPHP\POLYFILL_COLOR_MIX`（`color-mix()`より前の静的カラーのフォールバック）。デフォルトは`POLYFILL_ALL`、`POLYFILL_NONE`は両方を無効にします |
| `importSearchPaths` | `array<string>` | ファイルシステムから`@import`を解決するときに検索するディレクトリ |

```php
use TailwindPHP\tw;
use const TailwindPHP\POLYFILL_NONE;

// Cache construction state on disk, reused by later requests
$compiler = tw::compile('@import "tailwindcss";', [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

// Plain output without fallbacks, e.g. for CSS modules
$compiler = tw::compile('@import "tailwindcss/utilities.css";', [
    'polyfills' => POLYFILL_NONE,
]);
$compiler->generate('<div class="bg-red-500/50">');
// .bg-red-500\/50 { background-color: color-mix(in oklab, var(--color-red-500) 50%, transparent); }
// (with the default, a `#fb2c3680` fallback comes first and color-mix() moves into @supports)
```

インスタンスで使えるメソッドの一覧は、[TailwindCompilerインスタンスメソッド](#tailwindcompiler-instance-methods)を参照してください。

## tw::properties()

```php
public static function properties(string|array $input, string $css = '@import "tailwindcss";'): array
```

クラスに対するCSS変数が未解決のままの**生の**CSSプロパティを返します。**戻り値** `array<string, string>`（プロパティ名 → 値）。

```php
use TailwindPHP\tw;

tw::properties('p-4');
// ['padding' => 'calc(var(--spacing) * 4)']

tw::properties(['flex', 'items-center', 'p-4']);
// ['display' => 'flex', 'align-items' => 'center', 'padding' => 'calc(var(--spacing) * 4)']
```

## tw::computedProperties()

```php
public static function computedProperties(string|array $input, string $css = '@import "tailwindcss";'): array
```

[`properties()`](#twproperties)と同様ですが、すべてのCSS変数を具体的な値に解決します。**戻り値** `array<string, string>`。

```php
use TailwindPHP\tw;

tw::computedProperties('p-4');
// ['padding' => '1rem']

tw::computedProperties('text-blue-500');
// ['color' => 'oklch(62.3% .214 259.815)']

tw::computedProperties(['flex', 'items-center', 'gap-4']);
// ['display' => 'flex', 'align-items' => 'center', 'gap' => '1rem']
```

## tw::value()

```php
public static function value(string|array $input, string $css = '@import "tailwindcss";'): ?string
```

単一のユーティリティクラスの**生の**値を返します。**戻り値** `?string` — ユーティリティが見つからない場合は`null`。

```php
use TailwindPHP\tw;

tw::value('p-4');           // 'calc(var(--spacing) * 4)'
tw::value('text-blue-500'); // 'var(--color-blue-500)'
```

## tw::computedValue()

```php
public static function computedValue(string|array $input, string $css = '@import "tailwindcss";'): ?string
```

単一のユーティリティクラスの**解決済み**の値を返します。**戻り値** `?string` — ユーティリティが見つからない場合は`null`。

```php
use TailwindPHP\tw;

tw::computedValue('p-4');           // '1rem'
tw::computedValue('text-blue-500'); // 'oklch(62.3% .214 259.815)'
tw::computedValue('gap-4');         // '1rem'
```

## tw::extractCandidates()

```php
public static function extractCandidates(string $html): array
```

コンテンツからTailwindのクラス名を抽出します（`class`属性と`className`属性の両方を読み取ります）。**戻り値** `array<string>`。

```php
use TailwindPHP\tw;

tw::extractCandidates('<div class="flex p-4" className="bg-blue-500">');
// ['flex', 'p-4', 'bg-blue-500']
```

## tw::extractCandidatesFromStrings()

```php
public static function extractCandidatesFromStrings(string $source): array
```

ソースコード内のすべてのシングルクォートまたはダブルクォートで囲まれた文字列からクラス名候補を抽出します。変数でクラスリストを組み立て、`class`属性を使わないテンプレート向けです。各文字列を空白で分割し、クラス名らしい各トークンを保持します。**戻り値** `array<string>`。

```php
use TailwindPHP\tw;

$classes = tw::extractCandidatesFromStrings('<?php $wrap = \'p-4 sm:flex\'; $title = "hello world"; ?>');
// ['p-4', 'sm:flex', 'hello', 'world']

$css = tw::compile()->css($classes);
```

通常の単語もチェックを通過します（上記の`hello`、`world`）。ただし、ユーティリティ名と一致しない限りコンパイル結果には何も生成されません。結果は[`css()`](#tailwindcompiler-instance-methods)に渡してください。`generate()`は`class`属性のみを読み取るためです。

## tw::cssMap()

```php
public static function cssMap(string $css = '@import "tailwindcss";'): array
```

CSS宣言からユーティリティクラスへの逆引きマップを作成します。既存のCSSをTailwindクラスに変換する場合に便利です。キーは変数を解決した`"property: value"`文字列で、複数プロパティのユーティリティには`"prop: value; prop: value"`キーも含まれます。値はクラス名です。**戻り値** `array<string, string>`。

```php
use TailwindPHP\tw;

$map = tw::cssMap();
$map['display: flex'];       // 'flex'
$map['padding: 1rem'];       // 'p-4'
$map['text-align: center'];  // 'text-center'
$map['color: #fff'];         // 'text-white'
```

このマップが対象とするのは、よく使われるユーティリティの固定リスト（display、position、flexbox、typography、spacingとsizeの各段階、border、黒・白・透明の色など）であり、すべてのユーティリティやthemeカラーではありません。`$css`引数は各ユーティリティの解決後の値を変更しますが、`--color-brand`などのカスタムthemeトークンは項目に追加されません。

## tw::minify()

```php
public static function minify(string $css): string
```

任意のCSS文字列をミニファイします。コメントを削除し、空白をまとめ、16進カラーを短縮し（`#ffffff` → `#fff`）、ゼロ値の単位を削除し（`0px` → `0`）、その他の最適化を行います。**戻り値** `string`。

CSSが自ら生成するTailwindPHPには、`minify`オプション（`tw::generate(['minify' => true])`）または[コンパイラーメソッド](#tailwindcompiler-instance-methods)の`$minify`パラメーターを使用してください。この方法ではシリアライズ中にミニファイするため高速で、文字列ベースの処理でまとめられてしまう子孫`:not()`セレクターも保持されます。

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="flex p-4">');
$minified = tw::minify($css);
```

最適化の全容は[キャッシュとミニファイ](https://tailwindphp.inline0.dev/ja/docs/advanced/caching)を参照してください。

## tw::clearCache()

```php
public static function clearCache(string|bool|null $cache = true): int
```

キャッシュされたCSSファイルを削除します。デフォルトのキャッシュディレクトリを使う場合は`true`（または省略）を渡し、カスタムディレクトリを使う場合はパス文字列を渡します。**戻り値** `int` — 削除したファイル数。

```php
use TailwindPHP\tw;

tw::clearCache();                  // default directory
tw::clearCache('/path/to/cache');  // custom directory
```

単独で使える`TailwindPHP\clearCache()`関数もあります。

## tw::colors()

```php
public static function colors(string $css = '@import "tailwindcss";'): array
```

theme内のすべてのカラー値を返します。**戻り値** `array<string, string>`（カラー名 → 計算後の値）。

```php
use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

// With a custom theme
tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']
```

## tw::breakpoints()

```php
public static function breakpoints(string $css = '@import "tailwindcss";'): array
```

theme内のすべてのブレークポイント値を返します。**戻り値** `array<string, string>`（ブレークポイント名 → 値）。

```php
use TailwindPHP\tw;

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']
```

## tw::spacing()

```php
public static function spacing(string $css = '@import "tailwindcss";'): array
```

themeのカスタムspacing値を返します。**戻り値** `array<string, string>`（spacing名 → 値）。

```php
use TailwindPHP\tw;

// TailwindCSS 4 uses a single --spacing base value rather than a --spacing-* namespace.
// This returns any custom --spacing-* values defined in the theme.
tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']
```

## 入力形式

検査メソッド（`generate`、`properties`、`computedProperties`、`value`、`computedValue`）は3種類の入力形式を受け付けます:

| 形式 | 例 |
|---|---|
| 文字列のみ | `tw::generate('<div class="flex">')` |
| 文字列 + CSS文字列 | `tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')` |
| `content`を含む配列（+ 任意の`css`） | `tw::generate(['content' => '<div class="flex">', 'css' => '@import "tailwindcss";'])` |

```php
use TailwindPHP\tw;

// Format 1: string only
tw::properties('p-4');

// Format 2: string + CSS
tw::properties('bg-brand', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

// Format 3: array
tw::properties(['content' => 'p-4', 'css' => '@import "tailwindcss";']);
```

## TailwindCompilerのインスタンスメソッド

[`tw::compile()`](#twcompile)が返すオブジェクトは、コンパイル時に使ったCSSに紐づく、静的クラスと同じ検査機能を備えています。呼び出しのたびにthemeを再解析せずに済みます。

```php
public function generate(string $content, bool $minify = false): string
public function css(array $candidates, bool $minify = false): string
public function generateExact(string $content, bool $minify = false): string
public function cssExact(array $candidates, bool $minify = false): string
public function extractCandidates(string $html): array
public function extractCandidatesFromStrings(string $source): array
public function properties(string|array $utilities): array
public function computedProperties(string|array $utilities): array
public function value(string $utility): ?string
public function computedValue(string $utility): ?string
public function minify(string $css): string
public function colors(): array
public function breakpoints(): array
public function spacing(): array
```

```php
use TailwindPHP\tw;

$compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

$css        = $compiler->generate('<div class="flex p-4 bg-brand">');
$candidates = $compiler->extractCandidates('<div class="flex p-4 bg-brand">');

$compiler->properties('bg-brand');          // ['background-color' => 'var(--color-brand)']
$compiler->computedProperties('bg-brand');   // ['background-color' => '#3b82f6']
$compiler->value('bg-brand');                // 'var(--color-brand)'
$compiler->computedValue('bg-brand');        // '#3b82f6'

$minified = $compiler->minify($css);

$compiler->colors();        // all color values
$compiler->breakpoints();   // all breakpoint values
$compiler->spacing();       // custom spacing values
```

### 蓄積生成と指定内容のみの生成

`generate()`と`css()`は**蓄積型**です。呼び出すたびに候補がコンパイラーの集合に追加され、返されるスタイルシートにはそれまでに確認したすべての内容が含まれます。テンプレートをまたいで1つのスタイルシートを構築する場合に適しています。

`generateExact()`と`cssExact()`は各呼び出しで指定されたコンテンツまたは候補のみを**厳密に**コンパイルし、前の呼び出しの内容は引き継ぎません。一方、解析済みのデザインシステムは再利用します。出力は同じコンテンツを新規に`tw::generate()`した場合と一致します。長期間使う1つのコンパイラーから、ページごとのCSSを構築する方法として最速です:

```php
use TailwindPHP\tw;

$compiler = tw::compile($themeCss);

foreach ($pages as $slug => $html) {
    $perPageCss[$slug] = $compiler->generateExact($html, true);
}
```

4つのメソッドはいずれも省略可能な`$minify`フラグを受け付けます。有効にするとシリアライズ時にCSSをミニファイします。`tw::generate(['minify' => true])`とバイト単位で一致し、整形済み出力を後からミニファイするより効率的です。

### 高度なインスペクター

コンパイル済みの状態を直接調べる場合:

```php
public function getTheme(): Theme
public function getDesignSystem(): object
public function getCompiled(): array
```

```php
$compiler->getTheme();        // Theme object with resolved values
$compiler->getDesignSystem(); // Design system: utilities, variants, etc.
$compiler->getCompiled();     // Raw compiled state array
```

これらは内部構造を返します。内容については[アーキテクチャ](https://tailwindphp.inline0.dev/ja/docs/advanced/architecture)を参照してください。

### 低レベル関数

`tw`クラスは`TailwindPHP`内の名前空間付き関数群をまとめています。`TailwindCompiler`ではなく、生のコンパイル結果が必要な場合に便利です:

| 関数 | 用途 |
|---|---|
| `compile(string $css, array $options = []): array` | CSSを解析してコンパイルします。`build`（蓄積型）と、候補と省略可能な`$minify`フラグを受け取る`buildExact`クロージャーに加え、`sources`、`root`、`features`、`designSystem`を返します。[`tw::compile()`](#twcompile)と同じオプションを受け付けますが、`stateCacheFile`は除きます |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | 永続的な[コンパイラー状態キャッシュ](https://tailwindphp.inline0.dev/ja/docs/advanced/caching#compiler-state-cache)を使って`compile()`します |
| `parseCssState()`、`finalizeCssState()`、`compileParsed()` | 解析の2段階（シリアライズ可能な状態の作成と、その状態から再構築するクロージャー）および`compileCssCached()`が使う最終組み立て処理です。`parseCss()`と`compileAst()`は、引き続き1段階で実行できる同等の関数です |

```php
use function TailwindPHP\compile;

$compiled = compile('@import "tailwindcss";');
$css = $compiled['build'](['flex', 'p-4'], true); // minified
```

## キャッシュ

`tw::generate()`はコンパイル済みのCSSをディスクにキャッシュし、同じ入力の再コンパイルを省けます。

| オプション | 型 | デフォルト | 用途 |
|---|---|---|---|
| `cache` | `bool \| string` | `false` | `true`でデフォルトのディレクトリを有効化します。パス文字列を指定すると、その場所にキャッシュします |
| `cacheTtl` | `int` | なし | キャッシュの有効期間（秒）。期限切れの項目は再コンパイルされます |

```php
use TailwindPHP\tw;

// Default directory: sys_get_temp_dir() . '/tailwindphp'
$css = tw::generate([
    'content' => '<div class="flex p-4">',
    'cache' => true,
]);

// Custom directory + TTL
$css = tw::generate([
    'content' => '<div class="flex p-4">',
    'cache' => '/path/to/cache',
    'cacheTtl' => 3600, // expire after 1 hour
]);
```

キャッシュキーは**コンテンツ**、**CSS設定**、**ミニファイ**オプションから導出されるため、入力ごとに異なるキャッシュファイルが作られます。[`tw::clearCache()`](#twclearcache)または単独の`TailwindPHP\clearCache()`関数で項目を消去できます。

詳しいガイドは[キャッシュとミニファイ](https://tailwindphp.inline0.dev/ja/docs/advanced/caching)を参照してください。