🪝 Como usar o Sistema de Hooks

Este documento explica como utilizar o sistema de Hooks (actions e filters) do SysCMS para estender funcionalidades sem alterar o núcleo.

🔎 Visão Geral

Hooks permitem que módulos e partes da aplicação "escutem" eventos (actions) ou transformem valores (filters).
São registrados e disparados em tempo de execução, com suporte a prioridades.

📚 Conceitos

Action: Executa callbacks quando um evento ocorre; não retorna valor (ex: enviar email após cadastro).
Filter: Executa callbacks encadeados que recebem um valor e retornam o valor, possivelmente modificado (ex: formatar texto).

🛠️ Helpers Disponíveis

Estes helpers são globais e estão disponíveis em todo o sistema:

add_action(string $hook, callable $listener, int $priority = 10): void
do_action(string $hook, ...$args): void
add_filter(string $hook, callable $listener, int $priority = 10): void
apply_filters(string $hook, mixed $value, ...$args): mixed

⚙️ Integração em Módulos

O ponto recomendado para registrar hooks de um módulo é um Service Provider.

Passo a Passo

Crie uma classe ServiceProvider no seu módulo.
Registre esta classe no module.json do módulo.
Dentro do método boot(), registre seus actions e filters.

Exemplo de Service Provider

namespace Modules\Contact;

use Modules\Contact\Models\Contact;

class ContactServiceProvider
{
    public function register(): void {}

    public function boot(): void
    {
        // Action: Dispara quando um contato é submetido
        add_action('contact.submitted', function (Contact $contact) {
            // Lógica para enviar email, logar, etc.
        }, 10);
        
        // Filter: Sanitiza a mensagem
        add_filter('contact.message_sanitize', function (string $message) {
            return trim(strip_tags($message));
        });
    }
}

Registro no `module.json`

{
  "providers": [
    "Modules\\Contact\\ContactServiceProvider"
  ]
}

💡 Exemplos Práticos

Disparando um Hook (Action)

// No controller ou serviço
$contact = new Contact($data);
$contact->save();

// Avisa o sistema que um contato foi submetido
do_action('contact.submitted', $contact);

Aplicando um Filtro

$mensagemOriginal = "  Olá <b>Mundo</b>  ";

// Permite que outros módulos modifiquem a mensagem antes de salvar
$mensagemFinal = apply_filters('contact.message_sanitize', $mensagemOriginal);

📨 Exemplo Real: Módulo de Contato

O módulo contact nativo do SysCMS utiliza hooks extensivamente:

Action contact.submitted: Envia um email para o administrador quando um novo contato é salvo.
Filter contact.message_sanitize: Limpa HTML e espaços em branco da mensagem antes de salvar.

Configuração de Email

Para que o envio de email funcione via hook, configure seu .env:

MAIL_TRANSPORT=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=seu_usuario
MAIL_PASSWORD=sua_senha
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@syscms.com

✅ Boas Práticas

Idempotência: Garanta que seus listeners possam ser executados múltiplas vezes sem efeitos colaterais indesejados.
Tratamento de Erros: Trate exceções dentro dos listeners para não quebrar o fluxo principal da aplicação.
Performance: Evite operações pesadas (como chamadas de API síncronas) em hooks críticos.
Segurança: Sempre sanitize dados em filters antes de retorná-los.

SysCMS Dev Team

3.7 KiB Executable File Raw Blame History