claude-plugins/perfex-dev/skills/perfex-hooks/SKILL.md

name, description, layer

name	description	layer
perfex-hooks	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.	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
• GitHub Hook List

---

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

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:

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

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

Exemplo:

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)

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

Exemplo:

// 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)

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

Exemplo:

// 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)

// 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)

// 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_