Referência para desenvolvedores

Hooks e desenvolvimento de plugins

Estenda o TubePress com seu sistema de hooks de ação e filtro no estilo WordPress: mais de 15 pontos de hook, o ciclo de vida do plugin e como criar e empacotar seu próprio plugin.

Plugins são a forma de adicionar funcionalidades ao TubePress sem modificar o núcleo. Eles se conectam ao CMS por meio de um sistema simples no estilo WordPress de actions (eventos disparados e esquecidos) e filters (modificam um valor e o retornam). Os três plugins incluídos — Age Gate, Backup Pro e CTR Ranking — são construídos inteiramente com a mesma API documentada aqui.

O sistema de hooks

A classe estática HookSystem gerencia ambos os tipos de hook. Os callbacks são executados em ordem crescente de prioridade (padrão 10); qualquer exceção lançada por um callback é capturada e registrada, para que um plugin com problema nunca derrube a página.

// Actions — do something when an event fires
HookSystem::addAction('head.meta', function () {
    echo '<meta name="rating" content="adult">';
}, 10);

// Filters — receive a value, return a (possibly) changed value
HookSystem::addFilter('theme.template_data', function ($data, $template) {
    if ($template === 'home') {
        $data['promo'] = Promo::current();
    }
    return $data;
});

Método	Propósito
`addAction($hook, $cb, $priority = 10)`	Registra um listener de action.
`doAction($hook, ...$args)`	Dispara uma action (chamado pelo núcleo).
`addFilter($hook, $cb, $priority = 10)`	Registra um filter.
`applyFilter($hook, $value, ...$args)`	Passa um valor por seus filters e o retorna.
`hasAction()` / `hasFilter()`	Verifica se há algo escutando.
`removeAction()` / `removeFilter()`	Remove todos os listeners de um hook.

Pontos de hook disponíveis

O núcleo dispara esses hooks. Você também pode definir e disparar os seus próprios a partir de um plugin.

Actions

Hook	Quando é disparado
`head.meta`	Dentro de `<head>`, após o CSS — adicione meta tags, tags de verificação, etc.
`footer.scripts`	Antes de `</body>`, após o JS — adicione analytics ou widgets.
`routes.registered`	Após todas as rotas do núcleo serem registradas, antes do catch-all de página.
`router.before_dispatch`	Imediatamente antes de um handler correspondente ser executado. Arg: o caminho resolvido.

Filters

Hook	Modifica (args)
`theme.template_data`	O array de dados antes de um template ser renderizado. Args: `($data, $templateName)`.
`head.css`	A string de saída CSS combinada.
`footer.scripts`	A string de saída JS combinada.
`video.card.html`	O HTML completo do video-card. Args: `($html, $video)`. Retorne uma string não vazia para substituí-lo.

Anatomia de um plugin

Um plugin é uma pasta dentro de plugins/ com um manifesto e uma classe que implementa PluginInterface.

plugins/myplugin/
├── plugin.json     Manifest (name, slug, version, …)
├── myplugin.php    Main class implementing PluginInterface
├── icon.svg        Optional icon shown in the admin
└── …               Your assets, templates, migrations

O manifesto é igual ao dos plugins incluídos:

{
  "name": "My Plugin",
  "slug": "myplugin",
  "description": "What it does, in one sentence.",
  "version": "1.0.0",
  "author": "You",
  "requires": "1.0.0",
  "icon": "icon.svg"
}

A classe principal implementa os seis métodos de ciclo de vida de PluginInterface:

Método	Chamado quando
`boot()`	Em cada requisição enquanto o plugin está ativo — registre hooks, rotas e assets aqui.
`activate()`	O administrador ativa o plugin.
`deactivate()`	O administrador o desativa.
`install()`	Primeira ativação — crie tabelas, inicialize configurações.
`uninstall()`	O plugin é removido — faça a limpeza.
`info()`	Retorna os dados do manifesto como um array.

Registrando rotas e assets

Faça toda a sua configuração em boot():

public function boot(): void
{
    // A front-end route
    Router::get('/promo/{code}', [PromoController::class, 'show']);

    // Inject a meta tag
    HookSystem::addAction('head.meta', [$this, 'meta']);

    // Tweak every video card
    HookSystem::addFilter('video.card.html', [$this, 'badge'], 20);
}

Autocontido por design. Um plugin deve adicionar tudo o que precisa — seu próprio esquema, configurações, rotas, páginas de administração e tarefas agendadas — e removê-los novamente ao desinstalar, sem alterações no CMS base. O plugin CTR Ranking é um bom modelo disso.

Tarefas agendadas em um plugin

Registre uma tarefa recorrente com o CronManager a partir de boot() — ele roda no pseudo-cron integrado, portanto não é necessário um crontab do sistema. É assim que o plugin CTR recalcula pontuações e o Backup Pro executa backups agendados.

Plugins incluídos como referências

Age GateOverlay, meta RTA, persistência de cookie. Backup ProPerfis, armazenamento remoto, agendamento. CTR RankingRastreamento, cron de recálculo, configuração de ordenação.

Distribuição e licenciamento

Você pode manter um plugin privado, compartilhá-lo livremente ou vendê-lo pelo marketplace, que adiciona licenciamento assinado e ativação por domínio. Consulte Theme development para o equivalente no lado de apresentação, e a referência da Theme API para tudo disponível ao código de template.

Ainda com dúvidas?

Abra um ticket pelo painel e nossa equipe vai ajudá-lo.

Experimente o demo ao vivo → Baixar TubePress →