First Commit

rules/14_COMO_USAR_HOOK.md

@@ -0,0 +1,133 @@
+# 🪝 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**