---
name: perfex-hooks
description: Sistema de hooks Perfex CRM — actions, filters, add_action, add_filter, do_action, apply_filters com lista completa por categoria. Baseado apenas na documentação oficial.
layer: wiki
---

# /perfex-hooks - Sistema de Hooks Perfex CRM

Sistema de extensibilidade via actions e filters. **Zero assumptions, zero hallucinations** - apenas documentação oficial.

---

## Documentação Base

- [Action Hooks](https://help.perfexcrm.com/action-hooks/)
- [GitHub Hook List](https://gist.github.com/JamesSimpson/4eae4ba2d6d7072eca9f0fae58b8887c)

---

## Conceitos Fundamentais

| Tipo | Função | Retorno | Uso |
|------|--------|---------|-----|
| **Action** | Executa lógica após eventos | void | Side effects (logs, emails, etc.) |
| **Filter** | Modifica dados antes de processamento | Dados modificados | Alterar valores |

---

## Sintaxe (v2.3.0+)

### Registar Action

```php
hooks()->add_action($tag, $callback, $priority = 10, $accepted_args = 1);
```

**Parâmetros:**
- `$tag` (string): Nome do hook
- `$callback` (callable): Função a executar
- `$priority` (int): Ordem de execução (menor = primeiro). Default: 10
- `$accepted_args` (int): Número de argumentos. Default: 1

**Exemplo:**

```php
// No init file do módulo
hooks()->add_action('after_client_added', 'meu_modulo_after_client_added');

function meu_modulo_after_client_added($clientId)
{
    // Lógica após cliente criado
    log_activity('Novo cliente criado: ' . $clientId);

    // Enviar notificação
    $CI = &get_instance();
    $CI->load->model('clients_model');
    $client = $CI->clients_model->get($clientId);

    // Integração externa, etc.
}
```

### Registar Filter

```php
hooks()->add_filter($tag, $callback, $priority = 10, $accepted_args = 1);
```

**Exemplo:**

```php
hooks()->add_filter('before_client_added', 'meu_modulo_before_client_added');

function meu_modulo_before_client_added($data)
{
    // Modificar dados antes de guardar
    if (empty($data['country'])) {
        $data['country'] = 177; // Portugal
    }

    // OBRIGATÓRIO: retornar dados modificados
    return $data;
}
```

### Executar Action (criar hooks próprios)

```php
hooks()->do_action($tag, $arg = '');
```

**Exemplo:**

```php
// No teu módulo, permitir que outros módulos executem código
hooks()->do_action('meu_modulo_after_process', $resultId);
```

### Aplicar Filter (criar filters próprios)

```php
hooks()->apply_filters($tag, $value, $additionalParams = []);
```

**Exemplo:**

```php
// Permitir que outros módulos modifiquem dados
$data = hooks()->apply_filters('meu_modulo_data', $data);
```

---

## Onde Colocar Hooks

### Opção 1: Init File do Módulo (Recomendado)

```php
// modules/meu_modulo/meu_modulo.php
hooks()->add_action('after_client_added', 'meu_modulo_client_handler');
```

### Opção 2: my_functions_helper.php (Customizações Simples)

```php
// application/helpers/my_functions_helper.php
hooks()->add_action('after_client_added', 'custom_client_handler');
```

---

## Lista Completa de Hooks por Categoria

### Autenticação

| Hook | Trigger | Argumentos |
|------|---------|------------|
| `admin_auth_init` | Início auth admin | - |
| `after_staff_login` | Após login staff | $staff_id |
| `after_user_logout` | Após logout | - |
| `after_contact_login` | Após login contacto | $contact_id |
| `after_client_register` | Após registo cliente | $client_id |
| `after_client_logout` | Após logout cliente | - |

### Clientes

| Hook | Trigger | Argumentos |
|------|---------|------------|
| `before_client_added` | **FILTER** - Antes de criar | $data |
| `after_client_added` | Após criar cliente | $client_id |
| `before_client_updated` | **FILTER** - Antes de actualizar | $data, $client_id |
| `after_client_updated` | Após actualizar | $client_id |
| `before_client_deleted` | Antes de apagar | $client_id |
| `after_client_deleted` | Após apagar | $client_id |
| `contact_created` | Contacto criado | $contact_id |
| `contact_updated` | Contacto actualizado | $contact_id |
| `before_delete_contact` | Antes apagar contacto | $contact_id |
| `contact_deleted` | Contacto apagado | $contact_id |

### Facturas

| Hook | Trigger | Argumentos |
|------|---------|------------|
| `before_invoice_added` | **FILTER** - Antes de criar | $data |
| `after_invoice_added` | Após criar | $invoice_id |
| `before_invoice_updated` | **FILTER** - Antes de actualizar | $data, $invoice_id |
| `after_invoice_updated` | Após actualizar | $invoice_id |
| `invoice_sent` | Factura enviada | $invoice_id |
| `invoice_status_changed` | Status alterado | $invoice_id, $status |
| `before_invoice_deleted` | Antes de apagar | $invoice_id |
| `invoice_marked_as_cancelled` | Factura cancelada | $invoice_id |

### Orçamentos (Estimates)

| Hook | Trigger | Argumentos |
|------|---------|------------|
| `before_estimate_added` | **FILTER** - Antes de criar | $data |
| `after_estimate_added` | Após criar | $estimate_id |
| `after_estimate_updated` | Após actualizar | $estimate_id |
| `estimate_