claude-plugins/perfex-dev/skills/perfex-module-basics/SKILL.md

name, description, layer

name	description	layer
perfex-module-basics	Fundamentos de desenvolvimento de módulos Perfex CRM — estrutura de pastas, ficheiro init, headers e integração CodeIgniter. Baseado apenas na documentação oficial.	wiki

/perfex-module-basics - Estrutura Base Módulos Perfex CRM

Fundamentos para desenvolvimento de módulos Perfex CRM. Zero assumptions, zero hallucinations - apenas documentação oficial.

---

Documentação Base

• Module Basics
• Introduction to Modules
• Module File Headers

---

Estrutura de Pastas (Obrigatória)

modules/
└── meu_modulo/
    ├── meu_modulo.php      # Init file (OBRIGATÓRIO - mesmo nome da pasta)
    ├── controllers/
    │   └── Meu_modulo.php
    ├── models/
    │   └── Meu_modulo_model.php
    ├── views/
    │   ├── index.php
    │   └── form.php
    ├── libraries/
    ├── helpers/
    ├── language/
    │   └── english/
    │       └── meu_modulo_lang.php
    ├── migrations/
    │   └── 001_version_100.php
    ├── config/
    └── index.html          # SEGURANÇA - prevenir directory listing

---

Init File (Obrigatório)

O ficheiro init é o ponto de entrada do módulo. DEVE ter o mesmo nome da pasta.

Template Mínimo

<?php

defined('BASEPATH') or exit('No direct script access allowed');

/*
Module Name: Meu Módulo
Description: Descrição do módulo
Version: 1.0.0
Requires at least: 2.3.*
Author: Descomplicar
Author URI: https://descomplicar.pt
*/

// Registar hooks de activação/desactivação
register_activation_hook('meu_modulo', 'meu_modulo_activation_hook');
register_deactivation_hook('meu_modulo', 'meu_modulo_deactivation_hook');
register_uninstall_hook('meu_modulo', 'meu_modulo_uninstall_hook');

/**
 * Executado quando o módulo é activado
 */
function meu_modulo_activation_hook()
{
    $CI = &get_instance();

    // Criar tabelas
    if (!$CI->db->table_exists(db_prefix() . 'meu_modulo')) {
        $CI->db->query('CREATE TABLE `' . db_prefix() . 'meu_modulo` (
            `id` INT(11) NOT NULL AUTO_INCREMENT,
            `name` VARCHAR(255) NOT NULL,
            `created_at` DATETIME NOT NULL,
            PRIMARY KEY (`id`)
        ) ENGINE=InnoDB DEFAULT CHARSET=' . $CI->db->char_set . ';');
    }

    // Adicionar opções
    add_option('meu_modulo_version', '1.0.0');
}

/**
 * Executado quando o módulo é desactivado
 */
function meu_modulo_deactivation_hook()
{
    // Limpeza temporária (não apagar dados)
}

/**
 * Executado quando o módulo é removido
 */
function meu_modulo_uninstall_hook()
{
    $CI = &get_instance();

    // Remover tabelas
    $CI->db->query('DROP TABLE IF EXISTS `' . db_prefix() . 'meu_modulo`');

    // Remover opções
    delete_option('meu_modulo_version');
}

---

File Headers (Meta-Informação)

Headers Obrigatórios

Header	Descrição
Module Name	ÚNICO OBRIGATÓRIO - Nome do módulo

Headers Opcionais (Recomendados)

Header	Descrição	Exemplo
Description	Descrição funcional	CRM integration module
Version	Versão semântica	1.0.0
Requires at least	Versão mínima Perfex	2.3.*
Author	Nome do autor	Descomplicar
Author URI	Website do autor	https://descomplicar.pt
Module URI	Página do módulo	https://...

Exemplo Completo

/*
Module Name: Customer Portal
Description: Extended customer self-service portal
Version: 2.1.0
Requires at least: 2.3.*
Author: Descomplicar
Author URI: https://descomplicar.pt
Module URI: https://descomplicar.pt/modules/customer-portal
*/

---

Aceder ao CodeIgniter

Fora de controllers/models, usar get_instance():

$CI = &get_instance();

// Carregar helper
$CI->load->helper('meu_modulo/meu_helper');

// Carregar library
$CI->load->library('meu_modulo/minha_library');

// Carregar model
$CI->load->model('meu_modulo/meu_modulo_model');

// Aceder à BD
$CI->db->get(db_prefix() . 'meu_modulo');

---

Funções de Módulo Essenciais

Paths e URLs

// URL do módulo
$url = module_dir_url('meu_modulo');
// Resultado: https://crm.exemplo.pt/modules/meu_modulo/

// Path absoluto
$path = module_dir_path('meu_modulo');
// Resultado: /var/www/html/modules/meu_modulo/

// Path das libraries
$libs_path = module_libs_path('meu_modulo');
// Resultado: /var/www/html/modules/meu_modulo/libraries/

Opções (Persistência)

// Criar opção (não sobrescreve se existir)
add_option('meu_modulo_setting', 'valor', 0);

// Ler opção
$valor = get_option('meu_modulo_setting');

// Actualizar opção (cria se não existir - v2.3.3+)
update_option('meu_modulo_setting', 'novo_valor');

// Apagar opção
delete_option('meu_modulo_setting');

Database Prefix

SEMPRE usar db_prefix() em queries:

// CORRECTO
$CI->db->get(db_prefix() . 'meu_modulo