# API

توجد الواجهة الساكنة كاملة في صنف واحد: `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";`، وتشمل السمات وpreflight والأدوات المساعدة. **القيمة المعادة** `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` | إدخال CSS يتضمن توجيهات Tailwind (الافتراضي `@import "tailwindcss";`) |
| `minify` | `bool` | تصغير المخرجات (الافتراضي `false`) |
| `importPaths` | `string \| array \| callable \| null` | تحميل CSS من نظام الملفات مع حل كامل لـ`@import` — راجع [استيراد CSS](https://tailwindphp.inline0.dev/ar/docs/usage/imports) |
| `cache` | `bool \| string` | تفعيل التخزين المؤقت للملفات — راجع [التخزين المؤقت](#caching) |
| `cacheTtl` | `int` | مدة صلاحية التخزين المؤقت بالثواني |

## tw::compile()

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

ينشئ `TailwindCompiler` قابلًا لإعادة الاستخدام ومرتبطًا بـCSS المعطى. يحدث التحليل وإنشاء نظام التصميم مرة واحدة، لذا فهو الخيار الكفء عند إنشاء CSS لعدة سلاسل محتوى مختلفة. استخدم `generate()` لتجميع ورقة أنماط واحدة عبر الاستدعاءات، أو [`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/ar/docs/advanced/caching#compiler-state-cache) |
| `polyfills` | `int` | أنواع القيم الاحتياطية المطلوب إصدارها، على هيئة قناع بتات من `TailwindPHP\POLYFILL_AT_PROPERTY` (القيم الافتراضية لـ`@layer properties` الخاصة بمتغيرات `@property`) و`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'
```

تغطي الخريطة قائمة ثابتة من الأدوات المساعدة الشائعة (العرض والموضع وflexbox والطباعة والتباعد وأحجام الخطوات والحدود والألوان السوداء والبيضاء والشفافة وما شابهها)، ولا تشمل كل أداة مساعدة أو لون سمة. يغيّر وسيط `$css` القيم المحلولة لتلك الأدوات المساعدة، لكن رموز السمات المخصصة (مثل `--color-brand`) لا تضيف مدخلات.

## tw::minify()

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

يُصغّر سلسلة CSS عشوائية: يزيل التعليقات، ويقلّص المسافات البيضاء، ويختصر ألوان hex ‏(`#ffffff` ← `#fff`)، ويحذف الوحدات من القيم الصفرية (`0px` ← `0`)، وغير ذلك. **القيمة المعادة** `string`.

بالنسبة إلى CSS الذي ينشئه TailwindPHP بنفسه، يُفضّل استخدام الخيار `minify` (`tw::generate(['minify' => true])`) أو المعامل `$minify` في [أساليب المترجم](#tailwindcompiler-instance-methods). فهذا المسار يصغّر أثناء التسلسل، وهو أسرع ويحافظ على محددات `:not()` للعناصر المتفرعة التي يختزلها المرور المعتمد على السلاسل النصية.

```php
use TailwindPHP\tw;

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

راجع [التخزين المؤقت والتصغير](https://tailwindphp.inline0.dev/ar/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
```

يعيد كل قيم الألوان من السمة. **القيمة المعادة** `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
```

يعيد كل قيم نقاط التوقف من السمة. **القيمة المعادة** `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
```

يعيد قيم التباعد المخصصة من السمة. **القيمة المعادة** `array<string, string>` (اسم التباعد ← القيمة).

```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`) ثلاثة أشكال للإدخال:

| التنسيق | المثال |
|---|---|
| سلسلة فقط | `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 الذي جُمّع به. استخدمه لتجنب إعادة تحليل السمة عند كل استدعاء.

```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()` بأسلوب **تراكمي**: يضيف كل استدعاء مرشحاته إلى المجموعة المتنامية للمترجم، وتغطي ورقة الأنماط المعادة كل ما تمت رؤيته حتى ذلك الحين. يناسب ذلك إنشاء ورقة أنماط واحدة عبر عدة قوالب.

تجمع `generateExact()` و`cssExact()` المحتوى أو المرشحين المحددين **بدقة** في كل استدعاء، دون ترحيل أي شيء بين الاستدعاءات، مع الاستمرار في إعادة استخدام نظام التصميم الذي حلله المترجم. تطابق المخرجات ما سينتج عن `tw::generate()` جديد للمحتوى نفسه. وهذه أسرع طريقة لإنشاء CSS لكل صفحة باستخدام مترجم واحد طويل العمر:

```php
use TailwindPHP\tw;

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

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

تقبل الأساليب الأربعة علامة `$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/ar/docs/advanced/architecture) لمعرفة محتوياتها.

### الدوال منخفضة المستوى

يلتف الصنف `tw` حول مجموعة من الدوال ذات مساحة الأسماء `TailwindPHP`. وهي مفيدة عندما تحتاج إلى نتيجة التجميع الخام بدلًا من `TailwindCompiler`:

| الدالة | الغرض |
|---|---|
| `compile(string $css, array $options = []): array` | تحلل CSS وتجمعه. تعيد `build` (تراكميًا) وإغلاقات `buildExact` تستقبل المرشحين وعلامة `$minify` اختيارية، بالإضافة إلى `sources` و`root` و`features` و`designSystem`. وتقبل الخيارات نفسها التي تقبلها [`tw::compile()`](#twcompile) باستثناء `stateCacheFile` |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` مع [ذاكرة حالة المترجم](https://tailwindphp.inline0.dev/ar/docs/advanced/caching#compiler-state-cache) الدائمة |
| `parseCssState()` و`finalizeCssState()` و`compileParsed()` | نصفا التحليل (حالة قابلة للتسلسل، ثم الإغلاقات المُعاد بناؤها منها) وخطوة التجميع النهائية التي يستخدمها `compileCssCached()`. يظل `parseCss()` و`compileAst()` مكافئين للخطوة الواحدة |

```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/ar/docs/advanced/caching).