perfex-module-dev

用途

本技能面向 Perfex CRM 模块架构工作。当用户创建、修改或调试 Perfex CRM 模块时使用，涉及 modules/<module_name>/ 目录下的任何内容，包括 module_name.php 等文件。目标是搭建遵循 Perfex 生命周期的模块——激活/停用钩子、幂等安装、正确命名的控制器和模型、符合 Perfex 的菜单与权限约定——使模块能跨 Perfex 升级存活，并在 macOS 开发环境与 Linux 生产环境表现一致。

模块基本概念

Perfex 模块是 modules/<module_name>/ 下的自包含文件夹，通过 Perfex 模块生命周期注册控制器、模型、视图、语言键和数据库表。模块在后台的 Setup → Modules 中激活。

最小模块结构

modules/my_module/ 下包含：

my_module.php：入口点，负责钩子、菜单注册、激活/停用
install.php：模块自有表的 DDL、初始选项
uninstall.php：删除表、删除选项（可选但推荐）
controllers/：My_module.php（后台控制器，类名必须与文件名匹配且首字母大写）以及 clients/My_module.php（客户区控制器）
models/：My_module_model.php（类名必须匹配：class My_module_model extends App_Model）
views/：index.php 及 clients/index.php
migrations/：110_version_110.php，每个 Version 一个，编号连续
language/：english/my_module_lang.php（$lang['key'] = '...';，由 register_language_files() 加载）及 french/my_module_lang.php
assets/：css/ 与 js/
config/：routes.php（可选，$route[...] 条目，由 HMVC 自动加载）与 csrf_exclude_uris.php（可选，返回 webhook URI 数组）

模块入口文件

入口文件顶部注释块不可省略，Perfex 会解析它以显示模块元数据；缺少 Version: 模块将不会显示为可安装。入口文件通过 hooks()->add_action('admin_init', ...) 注册菜单初始化，通过 register_language_files(MY_MODULE_NAME, [MY_MODULE_NAME]) 加载语言文件（这是受支持的方式，会处理当前语言、回退到英语，且无需了解 CI 加载器路径规则），并通过 register_activation_hook、register_deactivation_hook、register_uninstall_hook 注册生命周期钩子。

控制器模式

后台控制器继承 AdminController，客户区控制器继承 ClientsController，API 控制器继承 REST_Controller。控制器类名必须与文件名匹配且首字母大写（my_module.php → class My_module）。控制器内使用 has_permission() 检查权限，无权限时调用 access_denied()。

路由

Perfex 基于 CI/HMVC 约定自动路由：modules/my_module/controllers/My_module.php::index() 可通过 admin/my_module（后台控制器）或 my_module（客户控制器）访问。自定义路由可放在模块自有的 config/routes.php，HMVC 会自动加载。模块的 routes.php 仅当第一个 URI 段为模块名时才会被查询。自定义 URL 应放在 application/config/my_routes.php（核心会包含它且升级后保留）。切勿编辑 application/config/routes.php，它会在更新时被覆盖，且没有 app_routes 过滤钩子。

视图

以数组形式向视图传数据，使用 $this->load->view('my_module/index', $data)。视图内使用 init_head() 和 init_tail() 注入后台外壳；局部视图/AJAX 响应应跳过它们。核心视图可通过放置 my_ 前缀副本覆盖；模块视图需通过 add_module_support(MY_MODULE_NAME, 'my_prefixed_view_files') 显式启用该能力，否则 App_Loader 会跳过 my_ 查找。my_prefixed_view_files 是核心唯一识别的功能标志。

语言文件

语言文件位于 modules/my_module/language/<lang>/my_module_lang.php，文件名必须以 _lang.php 结尾，文件夹名为 Perfex 语言名。语言文件中切勿保留结尾 ?> 标签，否则后续以编程方式追加键时会出错。若当前语言文件夹无文件，Perfex 加载英语版本。管理员可在模块内添加 language/<lang>/custom_lang.php 覆盖字符串，它会在你的文件之后加载。CI 加载器按文件名缓存；若需强制重载语言文件，应使用直接 include() 并自行合并到 $this->lang->language。

安装、卸载与版本升级

任何 modules/ 下带有效头部注释块的文件夹都会自动出现在 Setup → Modules 列表。激活链接通过 register_activation_hook() 运行 install.php。激活钩子（及 install.php）在每次激活时都会触发，停用/重新激活会重新运行它；installed_version 仅在首次写入。因此 install.php 必须完全幂等，后续架构变更应放在 migrations/ 而非追加到 install.php。升级是手动的，部署不会触发，需在发布说明中提示点击 Upgrade Database。只有卸载会删除 tblmodules 行并运行 uninstall.php。版本号通过去掉点号映射到迁移编号（1.1.2 → 112），待执行迁移必须连续。

模块间依赖

Perfex 没有正式的依赖系统。若模块依赖另一模块的模型或助手，需自行处理优雅降级。可在头部注释中添加 Requires Module: 供管理员参考，但 Perfex 不强制执行。运行时加载需用 file_exists() 守卫。模块按管理员点击顺序激活，存在激活顺序问题，可采用延迟加载或检查两种激活顺序。其他模块卸载时 Perfex 不会向依赖模块触发钩子，唯一安全模式是每次跨模块调用都加守卫。不要硬编码跨模块路径，应使用加载器。

PHP 版本要求

Perfex 3.2.0+ 要求 PHP 8.1（强制，无法在 7.x/8.0 运行）；3.3.0+ 要求 PHP 8.1 并增加 PHP 8.4 兼容；Pre-3.2 官方支持 PHP 7.4+。PHP 8.4 会话变更（Perfex 3.3.0）：升级到 3.3.0 期间所有用户会因 PHP 8.4 会话兼容性变更而登出。模块的 Requires at least: 头部应匹配所依赖的 Perfex 版本。

Cron 任务注册

通过 register_cron_task() 注册模块 cron 工作（优于原始 after_cron_run 钩子）。Cron URL 为 wget -q -O- http://domain.com/cron/index，推荐间隔每 5-20 分钟。

常见陷阱

大小写：Linux 生产环境区分大小写，Mac 上可用的模型加载在 Linux 上可能失败。循环依赖：加载其他模块模型时用 file_exists() 包裹。权限：在激活钩子中通过 register_staff_capabilities() 注册权限，否则 ACL 会静默拒绝。

上游文档

Perfex 模块基础、模块文件头、常用模块函数、模块安全、CI3 控制器等官方文档链接见资料。内容已对照 Perfex CRM 3.4.0 核心源码验证。

技能介绍

用途