Discuz! X 插件开发手册

文件命名规范

Discuz! 按照如下的规范对程序和模板进行命名，请在设计插件时尽量遵循此命名规范：

• 可以直接通过浏览器访问的普通程序文件，以 .php 后缀命名。
• 被普通程序文件引用的程序文件，以 .inc.php 后缀命名。
• 被普通程序文件，或引用程序文件引用的函数库或类库，以 .func.php(函数库) 或 .class.php(类库) 后缀命名。
• 模板文件，以 .htm 后缀命名，插件模板文件存在于 source/plugin/identifier/template/ 目录中。
• 模板语言包文件，以 .lang.php 后缀命名，插件语言包文件开发时存放于 data/plugindata/ 目录中，文件名为 identifier.lang.php。
• 动态缓存文件，存放于 ./data/cache 目录中，依据不同的功用进行独立的命名。
• 使用后台数据备份功能生成的备份文件，通常以 .sql 为后缀，存放于 data/ 目录中。
• 有些目录中存在内容为空白的 index.htm 文件，此类文件是为了避免 Web 服务器打开 Directory Index 时可能产生的安全问题。

class_core.php 模块功能白皮书

source/class/class_core.php 是 Discuz! 的通用初始化模块程序，其几乎被所有的外部代码所引用，在您开始插件设计之前，可以先对该模块的大致功能做一定的了解。class_core.php 主要完成了以下任务：

• 对不同 PHP 及操作系统环境做了判断和兼容性处理，使得 Discuz! 可以运行于各种不同配置的服务器环境下。
• 初始化常量 IN_DISCUZ 为 TRUE，用于 include 或 require 后续程序的判断，避免其他程序被非法引用。
• 读取社区程序所在绝对路径，存放于常量 DISCUZ_ROOT 中。
• 加载所需的基本函数库 source/function/function_core.php。
• 通过 config/config_global.php 中提供的数据库账号信息，建立数据库连接。Discuz! 支持数据表的前缀，如需获得表的全名，可使用“DB::table('tablename')”方式。
• 判断用户是否登录，如登录标记 $_G['uid'] 为非 0，同时将 $_G['user']（加了 addslashes 的用户名，可用于不加修改的插入数据库）、 $_G['member']['username']（原始的用户名，可用于页面显示）、$_G['member']['password']（用户密码的MD5串）等相应用户信息赋值，其他用户信息存放于 $_G['member']，更多信息可通过“getuserprofile()”获取。
• 判断用户管理权限，将管理权限标记 $_G['adminid'] 为 1~3 中间的值。0 代表普通用户；1 代表论坛管理员；2 代表超级版主；3 代表论坛版主。将用户权限按照其所在的主用户组 ID 标记为 $_G['groupid']，相关权限从该 $_G['groupid'] 所对应的系统缓存中读出，存放于 $_G['group']。
• 预置读入了每个模块的各种设置变量。

插件接口概述

使用管理员账号登录 Discuz! 管理中心，在顶部菜单将可以看到“插件”菜单。“插件列表”列出了所有已安装的插件，是控制插件打开与否、设计插件模块、菜单、参数和使用权限的地方，插件开发者可以依照设计意图，在此进行插件的初步设置，这里同时也提供插件导入和插件开关的功能，用于导入他人设计的插件和对插件的可用状态进行变更。

开始编写一个新插件，请首先在插件管理中选择“设计新插件”，填写插件名称，名称用于表明此插件的用途，例如设置为“虚拟银行插件”。惟一标识符用于在后续的插件模块中调用本插件，不可与现有插件重复，命名规则限制与 PHP 变量命名相同，虽然初次设置后仍可改动，但强烈建议一次性将此配置设置好，否则可能涉及到很多代码方面的变更，增加编码的麻烦。请注意：惟一标识符请不要设置的过短，或使用有可能与其他插件重复的命名，例如制作此插件的公司叫做 Comsenz Inc.，插件名称是“虚拟银行插件”，惟一标识符可设置为“comsenz_virtual_bank”，后面将以“虚拟银行插件”和“comsenz_virtual_bank”为例进行说明。

在 source/plugin/ 目录中创建与唯一标识符同名的目录名，如 source/plugin/comsenz_virtual_bank/。

在插件管理中添加插件后，仅仅是增加了一条插件记录，后面还需要很多相关的设计和设置。在列表中选择插件的“详情”进入插件的详细设置。插件设置分为三个部分：

插件基本设置：
设置插件的基本参数，配置项目右边括号中的内容，为此设置对应的参数名称，调用方法将在后面的《参数读取与缓存控制》中详细说明。

 

插件模块：
插件模块分为程序链接、扩展项目和程序脚本 3 类：

• 程序链接 导航栏项目：可在前台导航栏增加一个菜单项，可自主指派菜单链接的 URL，也可以调用插件的一个模块，模块文件名指派为 source/plugin/插件目录/插件模块名.inc.php”。注意：由于引用外部程序，因此即便设置了模块的使用等级，您的程序仍需进行判断使用等级是否合法。
• 程序链接 导航栏 - 插件菜单项目：可在前台导航栏的插件子菜单中增加一个菜单项。
• 扩展项目 个人面板：可在个人面板上部增加一个菜单项。
• 扩展项目 个人面板 - 个人资料：可在个人面板的个人资料页上部增加一个菜单项。
• 扩展项目 个人面板 - 积分和用户组：可在个人面板的积分和用户组页上部增加一个菜单项。
• 扩展项目 站点帮助：可在站点帮助增加一个菜单项。
• 扩展项目 管理面板 - 基本：可在前台论坛管理面板侧边上部增加一个菜单项。
• 扩展项目 管理面板 - 工具：可在前台论坛管理面板侧边下部增加一个菜单项。
• 扩展项目 管理中心：可在后台插件栏目中为此插件增添一个管理模块。
• 程序脚本 页面嵌入：设置一个包含页面嵌入脚本的模块，模块文件名指派为 source/plugin/插件目录/插件模块名.class.php”。（页面嵌入将在后面的《页面嵌入模块开发》中详细说明）
• 程序脚本 特殊主题：设置一个特殊主题脚本的模块，模块文件名指派为 source/plugin/插件目录/插件模块名.class.php”。（特殊主题将在后面的《特殊主题模块开发》中详细说明）

您可以为每个模块设置不同的使用等级，例如设置为“超级版主”，则超级版主及更高的管理者可以使用此模块。

 

插件变量配置：
插件接口中提供了一个通用的插件配置管理程序，在大多数情况下可实现插件的参数配置，省却了插件开发者自行编写后台管理模块（即上面提到的“扩展项目 管理中心”模块）的麻烦。通常情况下，应优先使用通用插件配置管理程序来实现插件的参数配置，只有在通用程序确实无法实现时，才自行编写后台管理模块。输入配置名称和配置变量名、选择合适的配置类型后，即可为此插件增加一个配置变量，点“详情”可以编辑此配置变量的更多信息。为了方便插件程序调用使用者配置好的参数，配置变量同样被存放在了缓存文件中，读取方法将在后面的《参数读取与缓存控制》中详细说明。

注意：您只有在插件管理中将插件设置为“可用”，以上设置才能生效。

参数读取与缓存控制

编写插件程序时，可能需要读取一些插件的信息，如果插件需要使用者进行配置，还需要读取使用者设置的参数值。Discuz! 允许插件程序使用数据库读取和缓存读取这两种方法获取插件信息和参数。Discuz! 的插件接口已经对插件信息进行了合理的缓存，使用缓存读取的方式，将比数据库读取速度更快，消耗的资源更是几乎可以忽略不计。缓存读取唯一的局限是需要插件使用插件接口提供的通用后台管理程序。如果使用自定义后台模块的方式，需要后台模块将参数存放到 pluginvars 数据表中，才能被系统正常缓存。我们强烈推荐您通过缓存读取插件信息和配置数据。 插件参数读取 由于调用系统缓存统一通过“loadcache()”函数调用，并存放于 $_G['cache'] 中，因此“loadcache('plugin')”后可加载插件的缓存并存放于 $_G['cache']['plugin'] 中。嵌入点插件和以 plugin.php 为主脚本调用的插件无需加载此缓存，系统已自动加载了缓存。

页面嵌入模块开发

页面嵌入类型脚本格式 identifier { function HookId_1() { ...... return ...; } function HookId_2() { ...... return ...; } ...... } //全局脚本嵌入点类 class plugin_identifier_CURSCRIPT extends plugin_identifier { function HookId_1() { ...... return ...; } function HookId_2() { ...... return ...; } ...... } ?> identifier 插件的唯一标识符，在插件设置中设置。 CURSCRIPT 嵌入点位于的脚本名，如 forum.php 为 forum。 HookId 可用函数名以及被调用的脚本请看下面的介绍。这些函数将在 Discuz! 所有模块执行前调用。如果要在模板输出前调用，需在函数名结尾加上“_output”。全局调用的函数(“global_”开头的)在模板输出前调用。 如：viewthread_imicons() 在模块执行前调用，viewthread_imicons_output() 在模板输出前调用。 要查看所有的预定义嵌入点可通过查找 source/class/class_template.php 中找到以下代码，去除 //for Developer 注释后，更新缓存即可查到。 $dev = '';//for Developer $dev = "echo '[$hookid]';"; 预定义的嵌入点会在页面预置好的位置输出函数返回的内容。函数返回值类型如果是 array 且是空值的，必须输出一个空数组，如： return array(); 函数名并不限于以上列表，您可以自定义，只要符合以下规则，函数就会在适当的地方被调用。 function CURMODULE_USERDEFINE[_output]() CURMODULE 指明了此函数在哪个模块执行，可通过常量 CURMODULE 得到当前页面的 CURMODULE 值。USERDEFINE 可自定义，如果函数名以“_output”结尾则会在模板输出前调用，否则会在模块执行前调用。 如：attachment_test() 函数会在论坛的下载附件的时候执行。 “_output”结尾的函数的第一个参数为数组，含义为 array('template' => 要输出的模板名, 'message' => showmessage 的文字) 如：以下函数将在登录的时候输出调试文字 function logging_test_output($a) { print_r($a); print_r($_POST); } plugin_identifier 类中的其它函数为了便于阅读建议以“_”开头，如：

特殊主题模块开发

特殊主题模块用于创建一个特殊主题，特殊主题类型脚本格式 identifier { var $name = 'XX主题'; //主题类型名称 var $buttontext = '发布xx主题'; //发帖时按钮文字 function newthread($fid) { return ...; } function newthread_submit($fid) { } function newthread_submit_end($fid) { } function editpost() { return ...; } function editpost_submit() { } function editpost_submit_end() { } function newreply_submit_end() { } function viewthread() { return ...; } } ?> identifier 插件的唯一标识符，在插件设置中设置。 函数名以及含义 函数名 含义 newthread 发主题时页面新增的表单项目，通过 return 返回即可输出到发帖页面中 newthread_submit 主题发布后的数据判断 newthread_submit_end 主题发布后的数据处理 editpost 编辑主题时页面新增的表单项目，通过 return 返回即可输出到编辑主题页面中 editpost_submit 主题编辑后的数据判断 editpost_submit_end 主题编辑后的数据处理 newreply_submit_end 回帖后的数据处理 viewthread 查看主题时页面新增的内容，通过 return 返回即可输出到主题首贴页面中

扩展项目模块开发

扩展项目模块可以在社区的特定位置扩展出新的功能，通常用于扩展新的设置项目。 扩展项目的脚本文件以 .inc.php 结尾（如 test.inc.php），模版为固定文件名，位于插件目录的 template/ 子目录中，文件名与脚本名同名（如 test.htm），扩展名为 .htm。 添加相应的扩展项目模块时，需注明程序模块、菜单名称。例如我们添加个人面板项目，程序模块为 test，菜单名称是“测试”，当插件启用后，个人面板即家园的设置中会出现“测试”拓展项目。

第三方拓展类的开发

广告类 脚本位置：source/class/adv/adv_name.php 语言包位置：source/language/adv/adv_name.php name { var $version = '1.0';//脚本版本号 var $name = 'name';//广告类型名称 (可填写语言包项目) var $description = 'desc';//广告类型说明 (可填写语言包项目) var $copyright = 'Comsenz Inc.';//版权 (可填写语言包项目) var $targets = array('portal', 'home', 'member', 'forum', 'group', 'userapp', 'plugin', 'custom');//广告类型适用的投放范围 var $imagesizes = array('120x60', '120x240');//图片广告推荐大小 function getsetting() {//返回设置项目 $settings = array( 'text' => array( 'title' => 'text_title',//设置项目名称 (可填写语言项目) 'type' => 'mradio',//项目类型 'value' => array(),//项目选项 'default' => 0,//项目默认值 ) ); return $settings; } function setsetting(&$advnew, &$parameters) {//保存设置项目 } function evalcode() {//广告显示时的运行代码 return array( //检测广告是否投放时的代码 'check' => ' if(condition) { $checked = false; }', //广告显示时的代码 (随机调用投放的广告) 'create' => '$adcode = $codes[$adids[array_rand($adids)]];', ); } } ?> DIY 模块类 脚本位置：source/class/block/block_name.php 语言包位置：source/language/block/block_name.php name { function getsetting() {//返回设置项目 $settings = array( 'text' => array( 'title' => 'text_title',//设置项目名称 (可填写语言项目) 'type' => 'mradio',//项目类型 'value' => array(),//项目选项 'default' => 0,//项目默认值 ) ); return $settings; } function setsetting(&$advnew, &$parameters) {//保存设置项目 } function getdata($style, $parameter) {//模块返回的数据 } } ?> 要在 DIY 面板中增加模块脚本，需要在 source/include/portal/ 目录中新建一个文件 portal_blockclass_name.php，并在脚本中给 $blockclass 数组添加新值，即可在 DIY 面板中添加您设计的 DIY 模块了。例如： 道具类 脚本位置：source/class/magic/magic_name.php 语言包位置：source/language/magic/magic_name.php name { var $version = '1.0';//脚本版本号 var $name = 'name';//道具名称 (可填写语言包项目) var $description = 'desc';//道具说明 (可填写语言包项目) var $price = '10';//道具默认价格 var $weight = '10';//道具默认重量 var $copyright = 'Comsenz Inc.';//版权 (可填写语言包项目) function getsetting() {//返回设置项目 $settings = array( 'text' => array( 'title' => 'text_title',//设置项目名称 (可填写语言项目) 'type' => 'mradio',//项目类型 'value' => array(),//项目选项 'default' => 0,//项目默认值 ) ); return $settings; } function setsetting(&$advnew, &$parameters) {//保存设置项目 } function usesubmit($magic, $parameters) {//道具使用 } function show($magic) {//道具显示 } } ?> 任务类 脚本位置：source/class/task/task_name.php 语言包位置：source/language/task/task_name.php name { var $version = '1.0';//脚本版本号 var $name = 'name';//任务名称 (可填写语言包项目) var $description = 'desc';//任务说明 (可填写语言包项目) var $copyright = 'Comsenz Inc.';//版权 (可填写语言包项目) var $icon = '';//默认图标 var $period = '';//默认任务间隔周期 var $periodtype = 0;//默认任务间隔周期单位 var $conditions = array(//任务附加条件 'text' => array( 'title' => 'text_title',//设置项目名称 (可填写语言项目) 'type' => 'mradio',//项目类型 'value' => array(),//项目选项 'default' => 0,//项目默认值 'sort' => 'complete',//条件类型 (apply:申请任务条件 complete:完成任务条件) ), ); function preprocess($task) {//申请任务成功后的附加处理 } function csc($task = array()) {//判断任务是否完成 (返回 TRUE:成功 FALSE:失败 0:任务进行中进度未知或尚未开始 大于0的正数:任务进行中返回任务进度) } function sufprocess($task) {//完成任务后的附加处理 } function view($task, $taskvars) {//任务显示 } function install() {//任务安装的附加处理 } function uninstall() {//任务卸载的附加处理 } function upgrade() {//任务升级的附加处理 } } ?> 验证问答类 脚本位置：source/class/secqaa/secqaa_name.php 语言包位置：source/language/secqaa/secqaa_name.php name { var $version = '1.0';//脚本版本号 var $name = 'name';//验证问答名称 (可填写语言包项目) var $description = 'desc';//验证问答说明 (可填写语言包项目) var $copyright = 'Comsenz Inc.';//版权 (可填写语言包项目) function make(&$question) {//返回安全问答的答案和问题 ($question 为问题，函数返回值为答案) } } ?>

CSS 继承规范

Discuz!X 中 CSS 文件会在缓存时按照以下顺序进行合并： 1、template/default/*.css 文件 2、当默认模版是非默认模版时，template/模版目录/extend_*.css 文件 或 template/模版目录/*.css 3、当某插件启用时，source/plugin/插件目录/extend_*.css 文件 因此非默认模版目录中的 CSS 属性将继承默认模版中的 CSS 属性，插件目录中的 CSS 文件将继承前二者的 CSS 属性。

插件安装、卸载、升级脚本的设计

安装、卸载 插件作者可以设计 2 个脚本文件用于插件的安装和卸载，文件名任意。脚本中可用 runquery() 函数执行 SQL 语句，表名可以直接写“cdb_”。插件作者只需在导出的 XML 文件结尾加上安装、卸载脚本的文件名即可 安装、卸载程序中可随意设计页面的跳转，只要在插件安装、卸载结束时候输出添加以下代码即可。 $finish = TRUE; 升级 插件作者可以设计一个脚本文件用于插件的升级，文件名任意。脚本中可用 runquery() 函数执行 SQL 语句，表名可以直接写“cdb_”。插件作者只需在导出的 XML 文件结尾加上升级脚本的文件名即可 升级程序中可通过 $fromversion 和 $toversion 变量判断升级的具体版本号，并随意设计页面的跳转，只要在插件升级结束时候输出添加以下代码即可。 $finish = TRUE; 插件的当前版本号位于 XML 文件的以下分支中，可自行更改。 ...... 当前版本]]> ...... 授权协议、插件介绍 插件在安装的时候您可以自定义授权信息文本，文本支持 Discuz 代码，站长同意后才能安装插件。如果插件存在后台管理界面或者变量配置，那么插件介绍文本会显示在插件后台页面中。插件作者只需在导出的 XML 文件结尾加上以下内容即可 模板、语言包 插件中的语言包可以写到导出的 XML 文件结尾，这样在插件安装的时候会自动把语言包生成文件名为 data/plugindata/identifier.lang.php 的文件。插件开发时，可直接在后台开启语言包选项后编辑此语言包文件。 scriptlang 为脚本文件的语言包，templatelang 为模版文件的语言包，installlang 为安装、升级、卸载脚本用的语言包。 插件的模板文件可以放置在 plugin 目录下，如 source/plugin/hooktest/template 子目录下。页面嵌入模块的脚本中可用以下方式调用此目录下的模板。 脚本中调用插件模版： include template('hooktest:index_top'); 模版中调用插件模版： {template hooktest:index_top} 插件模版文件中的语言包中通过 {lang identifier:langvar} 方式调用，例如： {lang hooktest:text} 上例中对应的变量为语言包文件 data/plugin/identifier.lang.php 中 $templatelang['hooktest']['text'] 的值。脚本中引用语言包无需包含语言包文件，可直接使用变量。如插件脚本中可用变量 $scriptlang['hooktest']['text']，安装脚本中可用变量 $installlang['hooktest']['text']。 其他论坛数据导入 插件安装时可以直接导入一个或多个论坛数据，这些论坛数据包括数据调用(request)、表情(smilies)、风格(styles)的数据。在导出的 XML 文件结尾加上需要导入数据的类型和数据文件名即可，多个文件名用逗号(",")分隔。 discuz_request_test.xml,discuz_request_test2.xml]]> discuz_smilies_test.xml]]> discuz_styles_test.xml]]> 小提示 在新插件内核中，通过 plugin.php 方式访问的插件可直接通过 plugin.php?id=xxx:yyy 方式调用而无需再在后台定义为普通脚本模块，只要 plugins/xxx/yyy.inc.php 文件存在即可。如果 xxx 和 yyy 同名，可直接通过 plugin.php?id=xxx 方式访问。如果导出的 XML 文件名以 SC_GBK、SC_UTF8、TC_BIG5、TC_UTF8 结尾，显示的时候将直接显示为“简体”、“繁体”、“UTF8”等字样。

编写插件的原则与注意事项

请在您动手编写插件之前，还需要仔细的阅读以下原则，遵循这些原则，将有效的避免可能发生的问题： 所有与插件的程序，包括其全部的前后台程序，请全部放入 source/plugin/ 目录中，同时在插件的安装说明中指出，插件的文件需要复制到哪些目录。为了避免与其他插件冲突，请尽量建立 source/plugin/ 下的子目录，并将插件程序放置于子目录下，这样您编写的插件将获得更好的兼容性。 如果您的插件包含“导航栏”模块，该模块将统一用 plugin.php?identifier=xxx&module=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 为插件的惟一标识符，yyy 为模块名称。前台插件外壳程序 plugin.php 已经加载了通用初始化模块 /source/class/class_core.php，不需再次引用。 如果您的插件包含“管理中心”模块，该模块将统一用 admin.php?action=plugins&identifier=xxx&pmod=yyy 的方式调用，请在相应链接、表单中使用此方式。其中 xxx 和 yyy 的定义与“导航栏”模块中的相同。系统还允许用 admin.php?action=plugins&edit=$edit&pmod=$mod 的方式来生成链接和表单地址，$edit 和 $mod 变量已经被插件后台管理接口赋值，因此将这两个变量值带入 URL 中也是被支持的。由于后台模块是被 admin.php 调用，因此已加载了通用初始化模块 /source/class/class_core.php 并进行了后台管理人员权限验证，因此模块程序中可直接写功能代码，不需再进行验证。 请勿绕过插件的前后台外壳（plugin.php 和 admin.php）而以直接调用某程序的方式编写插件，因为这样既导致了用户使用不便，代码冗余和不规范，同时又产生了因验证程序考虑不周到而带来的安全隐患。您可以在任何地方，包括链接、表单等处方便的使用上述 URL 地址对插件模块进行调用。 所有与插件有关的程序，包括全部的前后台程序，因全部使用外壳调用，请务必在第一行加入 if(!defined('IN_DISCUZ')) { exit('Access Denied'); } 以免其被 URL 直接请求调用，产生安全问题。 一般情况下，您发布插件请使用插件导出的功能，以方便使用者一次性导入插件的配置数据，极特殊的情况下，也可以分步骤告知使用者如何进行插件配置管理和安装此插件。 如果功能独立，请尽量使用单独程序的方式编写插件（即外挂型插件），而尽量少的对论坛本身代码进行修改，这将为使用者今后的升级带来很大方便。 您可以修改 Discuz! 本身的数据结构，但更推荐在不很影响效率的前提下将插件数据用另外的数据表存储，因为不能排除您增加的字段或索引和今后版本 Discuz! 核心数据字段重名的可能。在任何情况下，请不要删除 Discuz! 标准版本数据结构中已有的字段或索引。 请在插件说明书中对插件做以详尽的描述，例如增加了哪些字段、哪些表，修改了或新增了哪些程序，版本兼容性，后续支持的提供方式（例如不提供支持，或以什么样的方式提供）。如果方便，请尽可能提供插件的卸载方法，例如去除哪些字段、删除哪些新增的程序、将哪些被插件修改的程序恢复原状等等，使用者会感激您为此付出的辛勤劳动，甚至愿意支付相应的费用支持您未来的发展。 如果插件使用另外的数据表存储，请在插件管理中准确的设置插件所使用的数据表名称（不包含前缀），这样用户在备份数据的时候，能够把插件数据一同备份。 Discuz! 内置了 8 种自定义积分，存储于 common_member 表中的 extcredits1 至 extcredits8 字段中，类型为有符号整数。