Discuz! X 插件开发手册

• 编写插件程序时，可能需要读取一些插件的信息，如果插件需要使用者进行配置，还需要读取使用者设置的参数值。Discuz! 允许插件程序使用数据库读取和缓存读取这两种方法获取插件信息和参数。Discuz! 的插件接口已经对插件信息进行了合理的缓存，使用缓存读取的方式，将比数据库读取速度更快，消耗的资源更是几乎可以忽略不计。缓存读取唯一的局限是需要插件使用插件接口提供的通用后台管理程序。如果使用自定义后台模块的方式，需要后台模块将参数存放到 pluginvars 数据表中，才能被系统正常缓存。我们强烈推荐您通过缓存读取插件信息和配置数据。

• 插件参数读取

  由于调用系统缓存统一通过“loadcache()”函数调用，并存放于 $_G[‘cache‘] 中，因此“loadcache(‘plugin‘)”后可加载插件的缓存并存放于 $_G[‘cache‘][‘plugin‘] 中。嵌入点插件和以 plugin.php 为主脚本调用的插件无需加载此缓存，系统已自动加载了缓存。

• 页面嵌入类型脚本格式

  <?php //全局嵌入点类（必须存在） class plugin_identifier { function HookId_1() { ...... return ...; } function HookId_2() { ...... return ...; } ...... } //全局脚本嵌入点类 class plugin_identifier_CURSCRIPTextends 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 类中的其它函数为了便于阅读建议以“_”开头，如：
  

  <?php class plugin_sample { function _updatecache() { ...... return ...; } } class plugin_sample_forum extends plugin_sample { function viewthread_posttop() { ...... return ...; } ...... } ?>

   

• 特殊主题模块用于创建一个特殊主题，特殊主题类型脚本格式

  <?php class threadplugin_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

  <?php class adv_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

  <?php class block_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 模块了。例如：

  <?php $blockclass[‘html‘][‘subs‘][‘html_html‘][‘script‘][‘my‘] = ‘我的DIY模块‘; ?>

• 道具类
  脚本位置：source/class/magic/magic_name.php
  语言包位置：source/language/magic/magic_name.php

  <?php class magic_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

  <?php class task_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

  <?php class secqaa_name { var $version = ‘1.0‘;//脚本版本号 var $name = ‘name‘;//验证问答名称 (可填写语言包项目) var $description = ‘desc‘;//验证问答说明 (可填写语言包项目) var $copyright = ‘Comsenz Inc.‘;//版权 (可填写语言包项目) function make(&$question) {//返回安全问答的答案和问题 ($question 为问题，函数返回值为答案) } } ?>

• 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 文件结尾加上安装、卸载脚本的文件名即可
  

  <item id="installfile"><![CDATA[install.php]]></item> <item id="uninstallfile"><![CDATA[uninstall.php]]></item> </item> </root>

  安装、卸载程序中可随意设计页面的跳转，只要在插件安装、卸载结束时候输出添加以下代码即可。

  $finish = TRUE;

• 升级
  插件作者可以设计一个脚本文件用于插件的升级，文件名任意。脚本中可用 runquery() 函数执行 SQL 语句，表名可以直接写“cdb_”。插件作者只需在导出的 XML 文件结尾加上升级脚本的文件名即可
  

  <item id="upgradefile"><![CDATA[upgrade.php]]></item> </item> </root>

  升级程序中可通过 $fromversion 和 $toversion 变量判断升级的具体版本号，并随意设计页面的跳转，只要在插件升级结束时候输出添加以下代码即可。

  $finish = TRUE;

  插件的当前版本号位于 XML 文件的以下分支中，可自行更改。

  <item id="plugin"> ...... <item id="version"><![CDATA[当前版本]]></item> ...... </item>

• 授权协议、插件介绍
  插件在安装的时候您可以自定义授权信息文本，文本支持 Discuz 代码，站长同意后才能安装插件。如果插件存在后台管理界面或者变量配置，那么插件介绍文本会显示在插件后台页面中。插件作者只需在导出的 XML 文件结尾加上以下内容即可

  <item id="license"><![CDATA[授权协议文本]]></item> <item id="intro"><![CDATA[插件介绍文本]]></item> </item> </root>

• 模板、语言包
  插件中的语言包可以写到导出的 XML 文件结尾，这样在插件安装的时候会自动把语言包生成文件名为 data/plugindata/identifier.lang.php 的文件。插件开发时，可直接在后台开启语言包选项后编辑此语言包文件。

  <item id="language"> <item id="scriptlang"> <item id="text"><![CDATA[脚本语言文字]]></item> </item> <item id="templatelang"> <item id="text"><![CDATA[模版语言文字]]></item> </item> <item id="installlang"> <item id="text"><![CDATA[安装语言文字]]></item> </item> </item> </item> </root>

  scriptlang 为脚本文件的语言包，templatelang 为模版文件的语言包，installlang 为安装、升级、卸载脚本用的语言包。
  插件的模板文件可以放置在 plugin 目录下，如 source/plugin/hooktest/template 子目录下。页面嵌入模块的脚本中可用以下方式调用此目录下的模板。
  脚本中调用插件模版：

  include template(‘hooktest:index_top‘);

  模版中调用插件模版：

  {template hooktest:index_top}

  插件模版文件中的语言包中通过 {lang identifier:langvar} 方式调用，例如：

  <!--{block return}--> {lang hooktest:text} <!--{/block}-->

  上例中对应的变量为语言包文件 data/plugin/identifier.lang.php 中 $templatelang[‘hooktest‘][‘text‘] 的值。脚本中引用语言包无需包含语言包文件，可直接使用变量。如插件脚本中可用变量 $scriptlang[‘hooktest‘][‘text‘]，安装脚本中可用变量 $installlang[‘hooktest‘][‘text‘]。
• 其他论坛数据导入
  插件安装时可以直接导入一个或多个论坛数据，这些论坛数据包括数据调用(request)、表情(smilies)、风格(styles)的数据。在导出的 XML 文件结尾加上需要导入数据的类型和数据文件名即可，多个文件名用逗号(",")分隔。

  <item id="importfile"> <item id="request"><![CDATA[discuz_request_test.xml,discuz_request_test2.xml]]></item> <item id="smilies"><![CDATA[discuz_smilies_test.xml]]></item> <item id="styles"><![CDATA[discuz_styles_test.xml]]></item> </item> </item> </root>

• 小提示
  在新插件内核中，通过 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 字段中，类型为有符号整数。