Discuz! X 插件开发手册-Discuz!运营教程-DZ插件网

Discuz! X 插件开发手册

镖师

2023/09/21 11:00:26

文件命名规范

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 时可能产生的安全问题。

[size=14px]class_core.php 模块功能白皮书[/size]

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']。

预置读入了每个模块的各种设置变量。

[size=14px]插件接口概述[/size]

使用管理员账号登录 Discuz! 管理中心，在顶部菜单将可以看到“插件”菜单。“插件列表”列出了所有已安装的插件，是控制插件打开与否、设计插件模块、菜单、参数和使用权限的地方，插件开发者可以依照设计意图，在此进行插件的初步设置，这里同时也提供插件导入和插件开关的功能，用于导入他人设计的插件和对插件的可用状态进行变更。
开始编写一个新插件，请首先在插件管理中选择“设计新插件”，填写插件名称，名称用于表明此插件的用途，例如设置为“虚拟银行插件”。惟一标识符用于在后续的插件模块中调用本插件，不可与现有插件重复，命名规则限制与 PHP 变量命名相同，虽然初次设置后仍可改动，但强烈建议一次性将此配置设置好，否则可能涉及到很多代码方面的变更，增加编码的麻烦。请注意：惟一标识符请不要设置的过短，或使用有可能与其他插件重复的命名，例如制作此插件的公司叫做 Comsenz Inc.，插件名称是“虚拟银行插件”，惟一标识符可设置为“comsenz_virtual_bank”，后面将以“虚拟银行插件”和“comsenz_virtual_bank”为例进行说明。
在 source/plugin/ 目录中创建与唯一标识符同名的目录名，如 source/plugin/comsenz_virtual_bank/。
在插件管理中添加插件后，仅仅是增加了一条插件记录，后面还需要很多相关的设计和设置。在列表中选择插件的“详情”进入插件的详细设置。插件设置分为三个部分：

插件基本设置：
设置插件的基本参数，配置项目右边括号中的内容，为此设置对应的参数名称，调用方法将在后面的《参数读取与缓存控制》中详细说明。
插件模块：
插件模块分为程序链接、扩展项目和程序脚本 3 类：
您可以为每个模块设置不同的使用等级，例如设置为“超级版主”，则超级版主及更高的管理者可以使用此模块。
插件变量配置：
插件接口中提供了一个通用的插件配置管理程序，在大多数情况下可实现插件的参数配置，省却了插件开发者自行编写后台管理模块（即上面提到的“扩展项目管理中心”模块）的麻烦。通常情况下，应优先使用通用插件配置管理程序来实现插件的参数配置，只有在通用程序确实无法实现时，才自行编写后台管理模块。输入配置名称和配置变量名、选择合适的配置类型后，即可为此插件增加一个配置变量，点“详情”可以编辑此配置变量的更多信息。为了方便插件程序调用使用者配置好的参数，配置变量同样被存放在了缓存文件中，读取方法将在后面的《参数读取与缓存控制》中详细说明。注意：您只有在插件管理中将插件设置为“可用”，以上设置才能生效。

参数读取与缓存控制

Discuz

页面嵌入模块开发

页面嵌入类型脚本格式

<?php //全局嵌入点类（必须存在）
   class plugin_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 类中的其它函数为了便于阅读建议以“_”开头，如：

<?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 为问题，函数返回值为答案) }
} ?>

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 文件结尾加上安装、卸载脚本的文件名即可
<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 的文件。插件开发时，可直接在后台开启语言包选项后编辑此语言包文件。

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 文件结尾加上需要导入数据的类型和数据文件名即可，多个文件名用逗号(",")分隔。

小提示
在新插件内核中，通过 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”等字样。

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

请在您动手编写插件之前，还需要仔细的阅读以下原则，遵循这些原则，将有效的避免可能发生的问题：

其全部的前后台程序

所有与插件有关的程序，包括全部的前后台程序，因全部使用外壳调用，请务必在第一行加入
if(!defined('IN_DISCUZ')) { exit('Access Denied'); }
以免其被 URL 直接请求调用，产生安全问题。一般情况下，您发布插件请使用插件导出的功能，以方便使用者一次性导入插件的配置数据，极特殊的情况下，也可以分步骤告知使用者如何进行插件配置管理和安装此插件。如果功能独立，请尽量使用单独程序的方式编写插件（即外挂型插件），而尽量少的对论坛本身代码进行修改，这将为使用者今后的升级带来很大方便。您可以修改 Discuz! 本身的数据结构，但更推荐在不很影响效率的前提下将插件数据用另外的数据表存储，因为不能排除您增加的字段或索引和今后版本 Discuz! 核心数据字段重名的可能。在任何情况下，请不要删除 Discuz! 标准版本数据结构中已有的字段或索引。请在插件说明书中对插件做以详尽的描述，例如增加了哪些字段、哪些表，修改了或新增了哪些程序，版本兼容性，后续支持的提供方式（例如不提供支持，或以什么样的方式提供）。如果方便，请尽可能提供插件的卸载方法，例如去除哪些字段、删除哪些新增的程序、将哪些被插件修改的程序恢复原状等等，使用者会感激您为此付出的辛勤劳动，甚至愿意支付相应的费用支持您未来的发展。如果插件使用另外的数据表存储，请在插件管理中准确的设置插件所使用的数据表名称（不包含前缀），这样用户在备份数据的时候，能够把插件数据一同备份。Discuz! 内置了 8 种自定义积分，存储于 common_member 表中的 extcredits1 至 extcredits8 字段中，类型为有符号整数。

进入原文参与互动