# Özel Eklentiler

Özel eklenti, `TailwindPHP\Plugin\PluginInterface` uygulayan bir PHP sınıfıdır. Bir `PluginAPI` örneği alır ve bunu statik ve işlevsel yardımcıları, bileşenleri ve varyantları kaydetmek için kullanır. `registerPlugin()` ile kaydedildikten sonra eklenti, `@plugin` yönergesinde adıyla çözümlenir; yerleşik tipografi ve formlar eklentileri de aynı mekanizmayı kullanır.

## `PluginInterface`

Üç yöntem uygulayın:

```php
namespace TailwindPHP\Plugin;

interface PluginInterface
{
    public function getName(): string;
    public function __invoke(PluginAPI $api, array $options = []): void;
    public function getThemeExtensions(array $options = []): array;
}
```

- `getName()`, `@plugin "..."` içinde kullanılan tanımlayıcıyı döndürür.
- `__invoke()` eklentiyi çalıştırır ve her şeyi `$api` üzerinden kaydeder. `$options` dizisi, `@plugin` CSS bloğundaki değerleri taşır.
- `getThemeExtensions()`, yardımcılar oluşturulmadan önce birleştirilecek tema ad alanlarını döndürür (yoksa `[]` döndürün).

## Örnek

```php
use TailwindPHP\Plugin\PluginInterface;
use TailwindPHP\Plugin\PluginAPI;

class MyCustomPlugin implements PluginInterface
{
    public function getName(): string
    {
        return 'my-custom-plugin';
    }

    public function __invoke(PluginAPI $api, array $options = []): void
    {
        // Static utilities
        $api->addUtilities([
            '.btn' => [
                'padding' => '0.5rem 1rem',
                'border-radius' => '0.25rem',
                'font-weight' => '600',
            ],
            '.btn-primary' => [
                'background-color' => 'blue',
                'color' => 'white',
            ],
        ]);

        // Functional utilities (generates .gutter-sm, .gutter-md, .gutter-lg)
        $api->matchUtilities(
            [
                'gutter' => fn ($value) => ['padding-inline' => $value],
            ],
            ['values' => ['sm' => '1rem', 'md' => '2rem', 'lg' => '3rem']]
        );

        // Component classes (sorted into the components layer)
        $api->addComponents([
            '.card' => [
                'background-color' => 'white',
                'border-radius' => '0.5rem',
                'padding' => '1rem',
            ],
        ]);

        // Custom variant (see the note below the API reference)
        $api->addVariant('hocus', '&:hover, &:focus');

        // Read a theme value
        $primary = $api->theme('colors.blue.500', '#3b82f6');
    }

    public function getThemeExtensions(array $options = []): array
    {
        return []; // Return theme additions if needed
    }
}
```

## `PluginAPI` başvurusu

API, TailwindCSS eklenti API arayüzünü yansıtır:

| Yöntem | İmza | Amaç |
|--------|------|------|
| `addBase` | `addBase(array $css): void` | Temel katman stilleri ekler. |
| `addUtilities` | `addUtilities(array $utilities, array $options = []): void` | Seçiciye göre anahtarlanmış statik yardımcı sınıfları kaydeder. |
| `matchUtilities` | `matchUtilities(array $utilities, array $options = []): void` | İşlevsel yardımcıları kaydeder; `$options['values']` değer eşlemesini sağlar, `$options['supportsNegativeValues']` negatif değerlere izin verir. |
| `addComponents` | `addComponents(array $components, array $options = []): void` | Bileşen sınıflarını kaydeder (bileşenler katmanı). |
| `matchComponents` | `matchComponents(array $components, array $options = []): void` | Değer eşlemeli işlevsel bileşenleri kaydeder. |
| `addVariant` | `addVariant(string $name, string\|array $variant): void` | Bir seçiciden statik varyant kaydeder. |
| `matchVariant` | `matchVariant(string $name, callable $callback, array $options = []): void` | İşlevsel varyant kaydeder; `$options['values']` değer eşlemesini sağlar. |
| `theme` | `theme(string $path, mixed $defaultValue = null): mixed` | Nokta yoluyla tema değerini okur (e.g. `colors.blue.500`). |
| `config` | `config(?string $path = null, mixed $defaultValue = null): mixed` | Nokta yoluyla bir yapılandırma değerini veya `$path` null ise yapılandırmanın tamamını okur. |
| `prefix` | `prefix(string $className): string` | Yapılandırılmış öneki sınıf adına uygular. |

`matchUtilities`, `matchComponents` ve `matchVariant` yöntemlerine geçirilen geri çağırım, değeri ve `modifier` anahtarını içeren ikinci bir bağımsız değişken dizisini alır.

Çekirdek Tailwind tarafından zaten kullanılmayan yardımcı adlarını seçin. Bir eklenti yardımcısı çekirdektekiyle aynı adı taşıdığında (örneğin çekirdek Tailwind'ın v4.3'ten beri `tab-size` için kullandığı `tab-*`), her iki bildirim aynı kurala eklenir ve çekirdekteki son sırada olduğundan o kazanır: `7` ile eşlenen bir eklenti `tab-4` yine `tab-size: 4` üretir.

> **Bilinen sorun:** `addVariant()` ile kaydedilen varyantlar ve `matchVariant()`'ın kaydettiği değer başına varyantlar mevcut sürümde uygulanmıyor. Yukarıdaki örnekteki `hocus:flex`, `:hover`/`:focus` seçicisi olmadan `.hocus\:flex { display: flex; }` biçimine derleniyor ([#10](https://github.com/inline0/tailwindphp/issues/10)). Bu düzeltilene kadar varyantı CSS içinde [`@custom-variant`](https://tailwindphp.inline0.dev/tr/docs/usage/directives#custom-variant) ile tanımlayın; bu yöntem çalışır: `@custom-variant hocus (&:hover, &:focus);`.

## Kaydetme ve kullanma

Eklenti örneğini kaydedin, ardından `getName()` içindeki adıyla başvurun:

```php
use TailwindPHP\tw;
use function TailwindPHP\registerPlugin;

registerPlugin(new MyCustomPlugin());

$css = tw::generate(
    '<div class="btn btn-primary card gutter-md">…</div>',
    '@plugin "my-custom-plugin"; @import "tailwindcss/utilities.css";'
);
```

[Eklentiler](https://tailwindphp.inline0.dev/tr/docs/plugins) sayfasında `@plugin` yönergesini, [Tema](https://tailwindphp.inline0.dev/tr/docs/usage/theme) sayfasında ise `$api->theme()` aracılığıyla sunulan değerleri görebilirsiniz.