Discuz插件制作教程【入门+精通+实战】.doc

一、开发插件所需资料与工具
1、DiscuzX3 插件机制
插件机制Discuz! 拥有一套完整的插件机制。
合理使用插件机制，你可以更好的将自己的个性功能需求整合到Discuz!产品中的同时，保持代码独立，并且不受后续Discuz!产品版本升级的影响。
我们鼓励并推荐，使用插件机制进行个性需求定制和研发。
插件设计的准备工作
插件实现流程
开始编写社区插件，您应当首先对插件实现的流程有一个大致的了解，以下是我们推荐的插件编写流程：
·
熟练使用 Discuz! 社区系统后，对希望完善或补充的个性化功能进行评估，进而提出插件的功能需求。
· 对插件做一个概括性的设计，例如：需要使用什么菜单、什么参数，配置哪些选项、数据结构如何设计、前后台实现哪些功能等等。
· 阅读本文档并在系统设置中实际体验 Discuz! 插件接口所实现的功用，例如：您的插件应当如何设计才能良好的挂接到社区系统中来。插件接口能够实现哪些功能、不能实现哪些功能，插件为此而需要做的优化、改造和取舍。
· 编写相应程序代码和模板语句，实现所需的功能并进行代码测试、兼容性测试和代码改进。
· 如果需要公开您的插件，可以用插件导出的方式，将插件配置信息导出到一个 XML 文件中，连同相应的程序和模板文件一同打包。同时，编写一个适合新手的插件的说明书也是必不可少的，其中包括：插件适用的 Discuz! 版本、功能概述、兼容性声明、安装方法、使用方法、卸载方法等等。
· 将插件提供给他人，或自己使用，根据使用者反馈，对插件进行完善。插件实现流程至此结束。
·
文件命名规范
Discuz! 按照如下的规范对程序和模板进行命名，请在设计插件时尽量遵循此命名规范：
· 可以直接通过浏览器访问的普通程序文件，以 .php 后缀命名。
· 被普通程序文件引用的程序文件，以 .inc.php 后缀命名。
· 被普通程序文件，或引用程序文件引用的函数库或类库，以 .func.php(函数库) 或 .class.php(类库) 后缀命名。
· 模板文件，以 .htm 后缀命名，插件模板文件存在于 source/plugin/identifier/template/ 目录中，手机版插件模板存在于 source/plugin/identifier/template/mobile/目录中
· 模板语言包文件，以 .lang.php 后缀命名，插件语言包文件开发时存放于 data/plugindata/ 目录中，文件名为identifier.lang.php。
· 动态缓存文件，存放于 ./data/cache 目录中，依据不同的功用进行独立的命名。
· 使用后台数据备份功能生成的备份文件，通常以 .sql 为后缀，存放于 data/ 目录中。
· 有些目录中存在内容为空白的 index.htm 文件，此类文件是为了避免 Web 服务器打开 Directory Index 时可能产生的安全问题。
· [X2.5新增内容] 从 Discuz! X2.5 开始，产品对数据表进行了封装，封装后的文件统一命名为 Table 类，通过“C::t(Table类文件名)”方式调用。插件如需封装自己的数据表，可将 Table 类文件存放于 source/plugin/identifier/table/ 目录下，并以 table_表名.php 格式命名，详见X2.5的新程序架构。
·
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['username']（加了 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']。
· 预置读入了每个模块的各种设置变量。
· [X2.5变更内容] $_G['username'] 将不进行 addslashes 处理。
插件接口概述
使用管理员账号登录 Discuz! 管理中心，在顶部菜单将可以看到“插件”菜单。“插件列表”列出了所有已安装的插件，是控制插件打开与否、设计插件模块、菜单、参数和使用权限的地方，插件开发者可以依照设计意图，在此进行插件的初步设置，这里同时也提供插件导入和插件开关的功能，用于导入他人设计的插件和对插件的可用状态进行变更。
开始编写一个新插件，请首先打开 config/config_global.php 文件，在文件结尾添加以下代码开启插件设计者模式。
· $_config['plugindeveloper'] = 1;
在插件管理中选择“设计新插件”，填写插件名称，名称用于表明此插件的用途，例如设置为“虚拟银行插件”。惟一标识符用于在后续的插件模块中调用本插件，不可与现有插件重复，命名规则限制与 PHP 变量命名相同，虽然初次设置后仍可改动，但强烈建议一次性将此配置设置好，否则可能涉及到很多代码方面的变更，增加编码的麻烦。请注意：惟一标识符请不要设置的过短，或使用有可能与其他插件重复的命名，例如制作此插件的公司叫做 Comsenz Inc.，插件名称是“虚拟银行插件”，惟一标识符可设置为“comsenz_virtual_bank”。最后在 source/plugin/ 目录中创建与唯一标识符同名的目录名，如 source/plugin/comsenz_virtual_bank/。

在插件管理中添加插件后，仅仅是增加了一条插件记录，后面还需要很多相关的设计和设置。在列表中选择插件的“详情”进入插件的详细设置。插件设置分为三个部分：
·
插件模块
插件模块分为程序链接、扩展项目和程序脚本 3 类：
程序链接 主导航项目：可在主导航栏增加一个菜单项，可自主指派菜单链接的 URL，也可以调用插件的一个模块，模块文件名指派为 source/plugin/插件目录/插件模块名.inc.php”。注意：由于引用外部程序，因此即便设置了模块的使用等级，您的程序仍需进行判断使用等级是否合法。
· 程序链接 主导航项目 - 插件菜单：可在主导航栏的插件子菜单中增加一个菜单项。
· 程序链接 顶部导航项目、底部导航项目、快捷导航项目、家园导航项目：可在各个导航中增加一个菜单项。
· 扩展项目 个人设置：可在个人设置中增加一个菜单项。
· 扩展项目 个人设置 - 个人资料：可在个人设置的个人资料页上部增加一个菜单项。
· 扩展项目 个人设置 - 积分：可在个人设置的积分页上部增加一个菜单项。
· 扩展项目 站点帮助：可在站点帮助中增加一个菜单项。
· 扩展项目 我的帖子：可在我的帖子中增加一个菜单项。
· 扩展项目 门户管理：可在门户管理面板上部增加一个菜单项。
· 扩展项目 论坛管理 - 基本：可在前台论坛管理面板侧边上部增加一个菜单项。
· 扩展项目 论坛管理 - 工具：可在前台论坛管理面板侧边下部增加一个菜单项。
· 扩展项目 管理中心：可在后台插件栏目中为此插件增添一个管理模块。
· 程序脚本 页面嵌入 - 普通版：设置一个包含页面嵌入脚本的模块，该模块用于在普通电脑访问的页面显示。模块文件名指派为 source/plugin/插件目录/插件模块名.class.php”。（页面嵌入将在后面的《页面嵌入模块开发》中详细说明）
· 程序脚本 页面嵌入 - 手机版：设置一个包含页面嵌入脚本的模块，该模块用于在手机访问的页面显示。
· 程序脚本 特殊主题：设置一个特殊主题脚本的模块，模块文件名指派为 source/plugin/插件目录/插件模块名.class.php”。（特殊主题将在后面的《特殊主题模块开发》中详细说明）
·
您可以为每个模块设置不同的使用等级，例如设置为“超级版主”，则超级版主及更高的管理者可以使用此模块。
扩展项目模块可以在社区的特定位置扩展出新的功能，通常用于扩展新的设置项目。项目的脚本文件以 .inc.php 结尾（如 test.inc.php），模版为固定文件名，位于插件目录的 template/ 子目录中，文件名与脚本名同名（如 test.htm），扩展名为 .htm。添加相应的扩展项目模块时，需注明程序模块、菜单名称。例如我们添加个人面板项目，程序模块为 test，菜单名称是“测试”，当插件启用后，个人面板即家园的设置中会出现“测试”拓展项目。
在新插件内核中，通过 plugin.php 方式访问的插件可直接通过 plugin.php?id=xxx:yyy 方式调用而无需再在后台定义为普通脚本模块，只要 source/plugin/xxx/yyy.inc.php 文件存在即可。如果 xxx 和 yyy 同名，可直接通过 plugin.php?id=xxx 方式访问。
插件变量配置
插件接口中提供了一个通用的插件配置管理程序，在大多数情况下可实现插件的参数配置，省却了插件开发者自行编写后台管理模块（即上面提到的“扩展项目 管理中心”模块）的麻烦。通常情况下，应优先使用通用插件配置管理程序来实现插件的参数配置，只有在通用程序确实无法实现时，才自行编写后台管理模块。输入配置名称和配置变量名、选择合适的配置类型后，即可为此插件增加一个配置变量，点“详情”可以编辑此配置变量的更多信息。为了方便插件程序调用使用者配置好的参数，配置变量同样被存放在了缓存文件中，读取方法将在后面的《插件的参数读取与缓存控制》中详细说明。
注意：您只有在插件管理中将插件设置为“可用”，以上设置才能生效。
插件的参数读取与缓存控制
· 编写插件程序时，可能需要读取一些插件的信息，如果插件需要使用者进行配置，还需要读取使用者设置的参数值。Discuz! 允许插件程序使用数据库读取和缓存读取这两种方法获取插件信息和参数。Discuz! 的插件接口已经对插件信息进行了合理的缓存，使用缓存读取的方式，将比数据库读取速度更快，消耗的资源更是几乎可以忽略不计。缓存读取唯一的局限是需要插件使用插件接口提供的通用后台管理程序。如果使用自定义后台模块的方式，需要后台模块将参数存放到 pluginvars 数据表中，才能被系统正常缓存。我们强烈推荐您通过缓存读取插件信息和配置数据。
·
由于调用系统缓存统一通过“loadcache()”函数调用，并存放于 $_G['cache'] 中，因此“loadcache('plugin')”后插件的变量缓会存放于 $_G['cache']['plugin'] 中。嵌入点插件和以 plugin.php 为主脚本调用的插件无需加载此缓存，系统已自动加载了缓存。变量配置类型为“版块/*”的变量会保存在 $_G['cache']['forums'][fid]['plugin'] 中。变量配置类型为“用户组/*”的变量会保存在 $_G['cache']['usergroup_groupid']['plugin'] 和 $_G['group']['plugin'] 中。
页面嵌入模块开发
页面嵌入类型脚本格式<?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 ...; } ......}?>
· plugin_
· 普通版脚本中的类名以 plugin_ 开头。手机版脚本中的类名以 mobileplugin_ 开头。
· identifier
· 插件的唯一标识符，在插件设置中设置。
· CURSCRIPT
· 嵌入点位于的脚本名，如 forum.php 为 forum。
· HookId

函数名
调用位置
声明位置
参数含义
HookId()
所有模块执行前被调用
脚本嵌入点类

HookId_output($value)
模块执行完毕，模板输出前被调用
脚本嵌入点类
$value: array('template' => 当前要输出的模版,'message' => showmessage 的信息内容,'values' => showmessage 的信息变量,
)
global_HookId()
模块执行完毕，模板输出前被调用
全局嵌入点类

HookId_message($value)
showmessage() 执行时调用
脚本嵌入点类
$value: array('param' => showmessage() 函数的参数数组,
)
ad_adId($value)
相应的广告位中调用
函数名为广告位脚本 ID 如：ad_headerbanner()
全局嵌入点类
脚本嵌入点类
$value: array('params' => 广告位参数,'content' => 当前广告位原本将要显示的内容,
)
common()
所有模块执行前被调用
全局嵌入点类

discuzcode($value)
discuzcode() 函数执行时调用
用于在帖子内容解析时嵌入自己的功能，函数中 $_G['discuzcodemessage'] 变量为待解析的字串
全局嵌入点类
$value: array('param' => caller 函数的参数数组,'caller' => caller 函数，此嵌入点被哪个函数调用'discuzcode' 被 discuzcode() 调用'messagecutstr' 被 messagecutstr() 调用
)
deletethread($value)
deletethread() 函数执行时调用
用于在主题删除前后嵌入自己的功能，此函数将在 deletethread() 中被调用 2 次，函数中 $_G['deletethreadtids'] 变量为待处理的 TID 数组
全局嵌入点类
$value: array('param' => deletethread() 函数的参数数组,'step' => 删除的步骤'check' 检测步骤'delete' 删除步骤
)
deletepost($value)
deletepost() 函数执行时调用
用于在帖子删除前后嵌入自己的功能，此函数将在 deletepost() 中被调用 2 次，函数中 $_G['deletepostids'] 变量为待处理的 ID 数组
全局嵌入点类
$value: array('param' => deletepost() 函数的参数数组,'step' => 删除的步骤'check' 检测步骤'delete' 删除步骤
)
avatar($value)
(X2.5 新增)
avatar() 函数执行时调用
用于在头像调用时嵌入自己的功能，函数中 $_G['hookavatar'] 变量为新头像返回值
全局嵌入点类
$value: array('param' => avatar() 函数的参数数组
)
profile_node($post, $start, $end)
(X3.0 新增)
贴内用户信息标记，返回值为标记显示内容
全局嵌入点类
$post: 当前帖子信息数组
$start: 用户填写的前置字符
$end: 用户填写的后置字符
要查看所有的预定义嵌入点，请打开 config/config_global.php 文件，将文件结尾添加的设计者模式值改成“2”，然后更新缓存即可。在页面源码中查找"<hook>"可搜索到嵌入点。（详细内容可参阅的《插件嵌入点列表》）
$_config['plugindeveloper'] = 2;
预定义的嵌入点会在页面预置好的位置输出函数返回的内容。函数返回值类型如果是 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 类中的其它函数为了便于阅读建议以“_”开头，如：
<?phpclass plugin_sample { function _updatecache() { ...... return ...; }}class plugin_sample_forum extends plugin_sample { function viewthread_posttop() { ...... return ...; } ......}?>

插件嵌入点列表
· 全局(common/)
extcredits.htm string spacecp_credit_extra faq.htm string faq_extra footer.htm string global_footer string global_footerlink header.htm string global_cpnav_top (X2.5) string global_cpnav_extra1 string global_cpnav_extra2 string global_qmenu_top (X3) string global_qmenu_bottom (X3) string global_nav_extra (X2.5) string global_header userabout.htm array global_userabout_top string userapp_menu_top string userapp_menu_middle array global_userabout_bottom userstatus.htm string global_usernav_extra1 string global_usernav_extra2 string global_usernav_extra3 string global_usernav_extra4 (X2.5)
· 论坛(forum/)
collection_all.htm (X2.5) string collection_index_top string collection_index_bottom collection_comment.htm (X2.5) string collection_nav_extra collection_index.htm (X2.5) string collection_index_top string collection_index_bottom collection_mycollection.htm (X2.5) string collection_index_top string collection_index_bottom collection_nav.htm (X2.5) string collection_nav_extra collection_view.htm (X2.5) string collection_viewoptions string collection_view_top string collection_threadlistbottom string collection_relatedop string collection_view_bottom string collection_side_bottom discuz.htm string index_status_extra string index_nav_extra (X2.5) string index_top string index_catlist_top (X2.5) array index_followcollection_extra (X3) array index_favforum_extra (X2.5) array index_favforum_extra (X3) array index_catlist (X2.5) array index_forum_extra (X2.5) array index_forum_extra (X2.5) array index_datacollection_extra (X3) string index_middle string index_bottom string index_side_top string index_side_bottom discuzcode.htm array viewthread_attach_extra (X2.5) editor_menu_forum.htm string post_image_btn_extra string post_image_tab_extra string post_attach_btn_extra string post_attach_tab_extra forumdisplay.htm string forumdisplay_leftside_top string forumdisplay_leftside_bottom string forumdisplay_forumaction string forumdisplay_modlink string forumdisplay_top string forumdisplay_middle string forumdisplay_postbutton_top string forumdisplay_threadtype_inner (X2.5) string forumdisplay_filter_extra (X2.5) string forumdisplay_threadtype_extra (X2.5) string forumdisplay_bottom string forumdisplay_side_top string forumdisplay_side_bottom forumdisplay_fastpost.htm string forumdisplay_fastpost_content string forumdisplay_fastpost_func_extra string forumdisplay_fastpost_ctrl_extra string global_login_text string forumdisplay_fastpost_upload_extend (X3) string forumdisplay_fastpost_btn_extra string forumdisplay_fastpost_sync_method forumdisplay_list.htm string forumdisplay_filter_extra array forumdisplay_thread array forumdisplay_thread_subject (X2.5) array forumdisplay_author array forumdisplay_thread (X2.5) array forumdisplay_author (X2.5) string forumdisplay_threadlist_bottom (X2.5) string forumdisplay_postbutton_bottom forumdisplay_sort.htm (X2.5) string forumdisplay_postbutton_bottom forumdisplay_subforum.htm (X2.5) array forumdisplay_subforum_extra array forumdisplay_subforum_extra guide.htm string guide_nav_extra string guide_top string guide_bottom index_navbar.htm string index_navbar post.htm string post_top string post_middle string post_btn_extra string post_sync_method string post_bottom string post_upload_extend (X3) post_activity.htm string post_activity_extra post_debate.htm string post_debate_extra post_editor_attribute.htm (X3) string post_attribute_extra string post_attribute_extra_body post_editor_body.htm string post_editorctrl_right string post_editorctrl_left string post_editorctrl_top string post_editorctrl_bottom post_infloat.htm string post_infloat_top string post_infloat_middle string post_infloat_btn_extra post_poll.htm string post_poll_extra string post_poll_upload_extend (X3) post_reward.htm string post_reward_extra post_trade.htm string post_trade_extra topicadmin_modlayer.htm string forumdisplay_modlayer string modcp_modlayer trade_info.htm string viewthread_tradeinfo_extra viewthread.htm string viewthread_top string viewthread_postbutton_top string viewthread_modoption string viewthread_beginline (X2.5) string viewthread_title_extra string viewthread_title_row string viewthread_middle string viewthread_bottom viewthread_activity.htm string viewthread_activity_extra1 string viewthread_activity_extra2 viewthread_album.htm (X3) string viewthread_beginline string viewthread_useraction_prefix string viewthread_useraction string viewthread_bottom viewthread_fastpost.htm string viewthread_fastpost_side string viewthread_fastpost_content string viewthread_fastpost_func_extra string viewthread_fastpost_ctrl_extra string global_login_text string viewthread_fastpost_upload_extend (X3) string viewthread_fastpost_btn_extra (X2.5) viewthread_from_node.htm array viewthread_postheader array viewthread_postheader array viewthread_postheader array viewthread_endline viewthread_node.htm array viewthread_profileside array viewthread_imicons array viewthread_magic_user array viewthread_avatar array viewthread_sidetop array viewthread_sidebottom array viewthread_postheader string viewthread_modaction (X2.5) string viewthread_share_method string viewthread_useraction array viewthread_postsightmlafter (X2.5) array viewthread_postfooter array viewthread_postaction (X2.5) string viewthread_magic_thread array viewthread_magic_post array viewthread_endline viewthread_node_body.htm array viewthread_posttop string global_login_text array viewthread_postbottom viewthread_poll.htm string viewthread_poll_top string viewthread_poll_bottom viewthread_portal.htm string viewthread_useraction_prefix string viewthread_useraction string viewthread_side_bottom viewthread_preview_node.htm (X3) array viewthread_postheader array viewthread_endline viewthread_trade.htm array viewthread_trade_extra