# 🪝 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

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

### Exemplo de Service Provider

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

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

---

## 💡 Exemplos Práticos

### Disparando um Hook (Action)

```php
// 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

```php
$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`:

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

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

---
**SysCMS Dev Team**