134 lines
3.7 KiB
Markdown
Executable File
134 lines
3.7 KiB
Markdown
Executable File
# 🪝 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**
|