perfex-module-dev

Perfex Module Development

You are a Perfex CRM module architect. Your job is to scaffold modules that respect Perfex's lifecycle — activation/deactivation hooks, idempotent installs, correctly-named controllers and models, and Perfex's menu and permission conventions — so they survive across Perfex upgrades and work identically on macOS dev and Linux production.

A Perfex module is a self-contained folder in modules/<module_name>/ that registers controllers, models, views, language keys, and DB tables through Perfex's module lifecycle. Modules are activated from Setup → Modules in the admin.

Minimum module structure

modules/my_module/
├── my_module.php              # entry point: hooks, menu registration, activation/deactivation
├── install.php                # DDL for module-owned tables, initial options
├── uninstall.php              # drop tables, delete options (optional but recommended)
├── controllers/
│   ├── My_module.php          # admin controller (class MUST match filename, capitalized)
│   └── clients/
│       └── My_module.php      # client-area controller
├── models/
│   └── My_module_model.php    # class MUST match: class My_module_model extends App_Model
├── views/
│   ├── index.php
│   └── clients/
│       └── index.php
├── migrations/
│   └── 110_version_110.php    # one per Version: bump, consecutive numbers (see perfex-database)
├── language/
│   ├── english/
│   │   └── my_module_lang.php # $lang['key'] = '...'; loaded by register_language_files()
│   └── french/
│       └── my_module_lang.php
├── assets/
│   ├── css/
│   └── js/
└── config/
    ├── routes.php             # optional: $route[...] entries, auto-loaded by HMVC
    └── csrf_exclude_uris.php  # optional: return [...] of webhook URIs (see perfex-security)

Module entry file (my_module.php)

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

/*
Module Name: My Module
Description: What it does
Version: 1.0.0
Requires at least: 2.9.*
Author: Your Name
*/

define('MY_MODULE_NAME', 'my_module');

hooks()->add_action('admin_init', 'my_module_init_menu_items');

// Loads modules/my_module/language/<active_lang>/my_module_lang.php for every request.
// Pass a second array arg to load more than one file from that folder.
register_language_files(MY_MODULE_NAME, [MY_MODULE_NAME]);

register_activation_hook(MY_MODULE_NAME, 'my_module_activation_hook');
register_deactivation_hook(MY_MODULE_NAME, 'my_module_deactivation_hook');
register_uninstall_hook(MY_MODULE_NAME, 'my_module_uninstall');

function my_module_activation_hook() {
    require_once(__DIR__ . '/install.php');
}

function my_module_init_menu_items() {
    $CI =& get_instance();
    $CI->app_menu->add_sidebar_menu_item('my-module', [
        'name'     => _l('my_module'),
        'href'     => admin_url('my_module'),
        'position' => 30,
        'icon'     => 'fa fa-cogs',
    ]);
}

register_language_files() is the supported way to load module language files — it handles the active language, falls back to English, and (unlike a manual $CI->lang->load() on app_init) doesn't need you to know the CI loader's path rules.

The comment block at the top is not optional — Perfex parses it to display module metadata. Missing Version: and the module won't show up as installable.

Controller pattern

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

class My_module extends AdminController {
    public function __construct() {
        parent::__construct();
        $this->load->model('my_module_model');
    }

    public function index() {
        if (!has_permission('my_module', '', 'view')) {
            access_denied('my_module');
        }
        $data['title'] = _l('my_module');
        $data['items'] = $this->my_module_model->get();
        $this->load->view('my_module/index', $data);
    }
}

• Admin controllers extend AdminController.
• Client area controllers extend ClientsController.
• API controllers extend REST_Controller.
• Controller class name MUST match filename, capitalized. my_module.php → class My_module.

Routes

Perfex auto-routes based on CI/HMVC convention: modules/my_module/controllers/My_module.php::index() is reachable at admin/my_module (admin controllers) or my_module (client controllers). For custom routes, ship a module-owned config/routes.php — HMVC loads it automatically:

// modules/my_module/config/routes.php
defined('BASEPATH') or exit('No direct script access allowed');

$route['my_module/custom/(:num)'] = 'my_module/custom/$1';

A module's routes.php is only consulted when the first URI segment is the module name (HMVC's Modules::parse_routes() looks in modules/<segment1>/config/routes.php). So $route['book/(:any)'] inside modules/my_module/config/routes.php never matches — book/abc looks in modules/book/. Vanity URLs go in application/config/my_routes.php, which core includes if present and which survives updates:

// application/config/my_routes.php
$route['book/([a-zA-Z0-9]+)'] = 'my_module/my_module_public/hash/$1';

Never edit application/config/routes.php — it's overwritten on update. There is no app_routes filter hook.

Views

Pass data to views as an array:

$data['foo'] = 'bar';
$this->load->view('my_module/index', $data);

Inside views/my_module/index.php:

<?php init_head(); ?>
<div id="wrapper">
    <div class="content">
        <h1><?= $title ?></h1>
    </div>
</div>
<?php init_tail(); ?>

init_head() and init_tail() inject the admin shell. Skip them on partials/AJAX responses.

Let admins override your views without editing them

Core views can be overridden by dropping a my_-prefixed copy next to them (my_index.php beside index.php — see perfex-theme). Module views get the same treatment only if the module opts in:

// my_module.php
add_module_support(MY_MODULE_NAME, 'my_prefixed_view_files');

Without this line, App_Loader skips the my_ lookup for anything under modules/my_module/views/. Opt in for any module you ship to other people — it's the difference between "customer edits your file and loses it on update" and a clean override. my_prefixed_view_files is the only feature flag core recognizes.

Language files

// modules/my_module/language/english/my_module_lang.php
$lang['my_module']                = 'My Module';
$lang['my_module_save']           = 'Save';
$lang['my_module_confirm_delete'] = 'Delete this item?';

Never leave a closing ?> tag in a language file — if you append keys programmatically later, the closing tag will break the append. This is explicitly a Perfex convention.

Register with register_language_files('my_module', ['my_module']) in the entry file (see above). The filename must end in _lang.php; the folder name is the Perfex language name (english, french, arabic…). If the active language folder has no file, Perfex loads the English one. Admins can add language/<lang>/custom_lang.php inside your module to override strings without touching your files — it's loaded after yours.

CI loader caches by filename. If you force-reload a language file for multi-locale switching, use direct include() and merge into $this->lang->language yourself — $this->lang->load() will return cached strings on second call.

Adding to the Setup → Modules list

No action needed. Any folder in modules/ with a valid header comment block shows up automatically. The activation link runs install.php via register_activation_hook().

Uninstalling

// uninstall.php
defined('BASEPATH') or exit('No direct script access allowed');

$CI =& get_instance();
$CI->db->query('DROP TABLE IF EXISTS ' . db_prefix() . 'my_module_items');
delete_option('my_module_setting');

Module version bumping and schema upgrades

Perfex records the header Version: in tblmodules.installed_version on first activation. When you later ship a higher Version:, Setup → Modules shows an Upgrade Database link next to the module; clicking it runs every modules/my_module/migrations/NNN_version_NNN.php above the installed number (see perfex-database for the file format).

• The activation hook (and therefore install.php) fires on every activation — deactivate/reactivate re-runs it. installed_version is only written the first time. That's why install.php must be fully idempotent, and why later schema changes belong in migrations/, not appended to install.php (a reactivate would otherwise re-apply them out of order).
• The upgrade is manual — a deploy doesn't trigger it. Put "click Upgrade Database" in your release notes.
• Only uninstall deletes the tblmodules row (and runs uninstall.php). Uninstalling is the only way to get install.php's "fresh install" path again.
• Version numbers map to migration numbers by stripping dots (1.1.2 → 112), and pending migrations must be consecutive — bump the last component by one per migration (see perfex-database).

Inter-module dependencies

Perfex has no formal dependency system. If your module depends on another module's model or helpers, you own the graceful-degradation path.

Declaring the dependency (for humans)

Add it to your module's header comment so admins know:

/*
Module Name: My Module
Description: Sends custom invoices based on Billing module data.
Requires Module: billing
Version: 1.0.0
*/

Requires Module: is not enforced by Perfex — it's documentation for the admin. You must still handle the runtime case where the required module is missing.

Runtime load with defensive guard

// ✅ Guard every cross-module load
$other_path = APPPATH . 'modules/billing/models/Billing_model.php';
if (!file_exists($other_path)) {
    log_message('info', 'my_module: billing module not installed, feature disabled');
    return;
}
$this->load->model('billing/billing_model');
$this->billing_model->do_something();

Activation-order problem

Modules activate in the order the admin clicks them. If my_module activates before billing, your app_init hook runs but billing/billing_model doesn't exist yet. Two patterns:

1. Lazy-load on use. Don't call the other module in app_init; wait until a real request needs it. Then the file_exists guard protects you.
2. Check both activation orders. If your activation hook needs the other module, gate it:

   function my_module_activation_hook() {
       if (!file_exists(APPPATH . 'modules/billing/module.php')) {
           set_alert('warning', 'My Module: install and activate Billing first, then reactivate My Module.');
           return;
       }
       require_once(__DIR__ . '/install.php');
   }
   

When the other module uninstalls

Perfex doesn't fire a "module X uninstalled" hook to dependent modules. The only safe pattern is: every cross-module call is guarded. There is no way to register a disable-callback. Assume the other module can vanish between any two requests.

Don't hardcode paths across modules

// ❌ fragile — breaks if the admin renames the module
include(APPPATH . 'modules/billing/helpers/billing_helper.php');

// ✅ use the loader which respects the module system
$this->load->helper('billing/billing');

PHP version requirements

Perfex version	Minimum PHP	Notes
3.2.0+	PHP 8.1	Enforced — won't run on 7.x/8.0
3.3.0+	PHP 8.1	PHP 8.4 compatibility added
Pre-3.2	PHP 7.4+	Officially supported

PHP 8.4 session change (Perfex 3.3.0): During update to 3.3.0, all users are logged out due to session compatibility changes for PHP 8.4. If your module stores session data beyond Perfex's default session handler, test that session data survives this transition.

Set your module's Requires at least: header to match the Perfex version you depend on:

/*
Requires at least: 3.2.*
*/

Cron task registration

Register module cron work via register_cron_task() (preferred over raw after_cron_run hook):

// module_name.php
register_cron_task('my_module_cron_handler');

function my_module_cron_handler() {
    // Runs after core cron tasks finish
    // Cron URL: wget -q -O- http://domain.com/cron/index
    // Recommended interval: every 5-20 minutes
}

This is cleaner than hooks()->add_action('after_cron_run', ...) and makes the cron dependency explicit.

Common pitfalls

• Capitalization: Linux production is case-sensitive. my_model.php loads as $this->my_model, but My_model.php works on Mac and fails on Linux if you call $this->load->model('my_model') vs $this->load->model('My_model') incorrectly.
• Circular dependencies: If your module loads another module's model, wrap with file_exists(APPPATH . 'modules/other/models/Other_model.php') — users may uninstall other while your module still references it.
• Permissions: Register permissions via register_staff_capabilities() in your activation hook, or the ACL will silently deny.

Related skills

• perfex-core-apis — every module registers hooks and uses the CI loader patterns documented there.
• perfex-database — install.php DDL conventions and foreign-key-to-core-table rules.
• perfex-customfields — programmatic custom-field install inside install.php.
• perfex-email — module-owned cron hooks for email retry processing.

Upstream docs

• Perfex module basics: https://help.perfexcrm.com/module-basics/
• Module file headers (the Version: format): https://help.perfexcrm.com/module-file-headers/
• Common module functions (register_activation_hook, register_cron_task, register_payment_gateway): https://help.perfexcrm.com/common-module-functions/
• Module security (direct-access prevention, path-traversal guards): https://help.perfexcrm.com/module-security/
• CI3 controllers: https://codeigniter.com/userguide3/general/controllers.html

---

Verified against Perfex CRM 3.4.0 core source on 2026-09-15 with scripts/verify-against-core.sh. Version-specific notes in the text are from official changelogs.