# Egyéni bővítmények

Az egyéni bővítmény egy PHP osztály, amely megvalósítja a `TailwindPHP\Plugin\PluginInterface` felületet. Kap egy `PluginAPI` példányt, és ezzel regisztrál statikus és funkcionális segédosztályokat, komponenseket, valamint változatokat. A `registerPlugin()` segítségével történő regisztrálás után a bővítmény neve feloldható egy `@plugin` direktívában — ugyanígy működnek a beépített tipográfiai és űrlapbővítmények is.

## `PluginInterface`

Valósítson meg három metódust:

```php
namespace TailwindPHP\Plugin;

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

- A `getName()` adja vissza a `@plugin "..."`-ben használt azonosítót.
- A `__invoke()` futtatja a bővítményt, és mindent a `$api` segítségével regisztrál. A `$options` tömb tartalmazza az `@plugin` CSS blokkból származó értékeket.
- A `getThemeExtensions()` a segédosztályok létrehozása előtt egyesítendő tématértereket adja vissza (ha nincs ilyen, adjon vissza `[]` értéket).

## Példa

```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` referencia

A API a TailwindCSS bővítmény API felületét követi:

| Metódus | Aláírás | Rendeltetés |
|--------|-----------|---------|
| `addBase` | `addBase(array $css): void` | Alaprétegbeli stílusok hozzáadása. |
| `addUtilities` | `addUtilities(array $utilities, array $options = []): void` | Szelektor szerint kulcsolt statikus segédosztályok regisztrálása. |
| `matchUtilities` | `matchUtilities(array $utilities, array $options = []): void` | Funkcionális segédosztályok regisztrálása; a `$options['values']` adja meg az értéktérképet, a `$options['supportsNegativeValues']` pedig engedélyezi a negatív értékeket. |
| `addComponents` | `addComponents(array $components, array $options = []): void` | Komponensosztályok regisztrálása (komponensréteg). |
| `matchComponents` | `matchComponents(array $components, array $options = []): void` | Funkcionális komponensek regisztrálása értéktérképpel. |
| `addVariant` | `addVariant(string $name, string\|array $variant): void` | Statikus változat regisztrálása szelektorból. |
| `matchVariant` | `matchVariant(string $name, callable $callback, array $options = []): void` | Funkcionális változat regisztrálása; az `$options['values']` adja meg az értéktérképet. |
| `theme` | `theme(string $path, mixed $defaultValue = null): mixed` | Témaérték beolvasása pontokkal elválasztott útvonal alapján (e.g. `colors.blue.500`). |
| `config` | `config(?string $path = null, mixed $defaultValue = null): mixed` | Konfigurációs érték beolvasása pontokkal elválasztott útvonal alapján, vagy a teljes konfiguráció beolvasása, ha a `$path` értéke null. |
| `prefix` | `prefix(string $className): string` | A beállított előtag alkalmazása egy osztálynévre. |

A `matchUtilities`, `matchComponents` és `matchVariant` részére átadott visszahívás az értéket, valamint egy második, `modifier` kulcsot tartalmazó argumentumtömböt kap.

Olyan segédosztályneveket válasszon, amelyeket a Tailwind még nem használ. Ha egy bővítmény segédosztálya megegyezik egy beépített nevével (például a `tab-*` névvel, amelyet a Tailwind a `tab-size` értékhez használ, mivel v4.3), mindkét deklaráció ugyanabba a szabályba kerül, és a beépített szabály szerepel később, ezért az érvényesül: a `tab-4` bővítmény `7` értékhez rendelve is `tab-size: 4`-t állít elő.

> **Ismert probléma:** a `addVariant()` segítségével regisztrált változatok és a `matchVariant()` által regisztrált értékenkénti változatok nem alkalmazódnak a jelenlegi kiadásban. A fenti példában szereplő `hocus:flex` `.hocus\:flex { display: flex; }`-ra fordul, `:hover`/`:focus` szelektor nélkül ([#10](https://github.com/inline0/tailwindphp/issues/10)). A javításig a változatot a CSS fájlban, a [`@custom-variant`](https://tailwindphp.inline0.dev/hu/docs/usage/directives#custom-variant) használatával határozza meg; ez működik: `@custom-variant hocus (&:hover, &:focus);`.

## Regisztrálás és használat

Regisztrálja a bővítménypéldányt, majd hivatkozzon rá a `getName()`-ből származó névvel:

```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";'
);
```

A `@plugin` direktíváról lásd a [Bővítmények](https://tailwindphp.inline0.dev/hu/docs/plugins) oldalt, a `$api->theme()` segítségével elérhető értékekről pedig a [Téma](https://tailwindphp.inline0.dev/hu/docs/usage/theme) oldalt.