Pular para o conteúdo

Plugins personalizados

Ver como Markdown Editar no GitHub Documentação em 3843abd

Um plugin personalizado é uma classe PHP que implementa TailwindPHP\Plugin\PluginInterface. Ele recebe uma instância de PluginAPI e a usa para registrar utilitários estáticos e funcionais, componentes e variantes. Depois de registrado com registerPlugin(), o plugin é encontrado pelo nome em uma diretiva @plugin — o mesmo mecanismo usado pelos plugins integrados de tipografia e formulários.

PluginInterface

Implemente três métodos:

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() retorna o identificador usado em @plugin "...".
  • __invoke() executa o plugin, registrando tudo por meio de $api. O array $options contém os valores do bloco @plugin CSS.
  • getThemeExtensions() retorna os namespaces do tema a serem mesclados antes da geração dos utilitários (retorne [] se não houver nenhum).

Exemplo

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
    }
}

referência de PluginAPI

O API espelha a TailwindCSS API do plugin:

Método Assinatura Finalidade
addBase addBase(array $css): void Adiciona estilos à camada base.
addUtilities addUtilities(array $utilities, array $options = []): void Registra classes utilitárias estáticas com base no seletor.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registra utilitários funcionais; $options['values'] fornece o mapa de valores, $options['supportsNegativeValues'] habilita valores negativos.
addComponents addComponents(array $components, array $options = []): void Registra classes de componentes (camada de componentes).
matchComponents matchComponents(array $components, array $options = []): void Registra componentes funcionais com um mapa de valores.
addVariant addVariant(string $name, string|array $variant): void Registra uma variante estática a partir de um seletor.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registra uma variante funcional; $options['values'] fornece o mapa de valores.
theme theme(string $path, mixed $defaultValue = null): mixed Lê um valor do tema usando um caminho de pontos (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Lê um valor de configuração usando um caminho de pontos ou a configuração inteira quando $path é null.
prefix prefix(string $className): string Aplica o prefixo configurado a um nome de classe.

O callback passado para matchUtilities, matchComponents e matchVariant recebe o valor e um array como segundo argumento, contendo uma chave modifier.

Escolha nomes de utilitários que o Tailwind principal ainda não use. Quando um utilitário de plugin tem o mesmo nome de um utilitário principal (por exemplo, tab-*, usado pelo Tailwind principal para tab-size desde v4.3), ambas as declarações ficam na mesma regra e a principal vem por último, prevalecendo: um tab-4 do plugin mapeado para 7 ainda gera tab-size: 4.

Problema conhecido: variantes registradas com addVariant() e variantes por valor registradas por matchVariant() não são aplicadas na versão atual. hocus:flex do exemplo acima compila para .hocus\:flex { display: flex; } sem seletor :hover/:focus (#10). Até que isso seja corrigido, defina a variante em CSS com @custom-variant, que funciona: @custom-variant hocus (&:hover, &:focus);.

Registro e uso

Registre a instância do plugin e depois faça referência a ele pelo nome de getName():

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

Consulte Plugins para ver a diretiva @plugin e Tema para conhecer os valores expostos por $api->theme().