DaoKecms 开发者文档

2.7 在模板里调用插件（防白屏守卫）

插件可能被站长停用，模板直接调用插件函数会致命错误。标准守卫写法：

<?php
/* header.php：插件核心函数不存在时，手动 require 插件 helpers */
if (!function_exists('adslot') && function_exists('plugin_dir')) {
    $asDir = plugin_dir('adslot');          // 目标插件目录（插件不存在返回空串）
    if ($asDir !== '' && is_file($asDir . '/helpers/adslot-core.php')) {
        require_once $asDir . '/helpers/adslot-core.php';
    }
    unset($asDir);
}
?>
<?php echo function_exists('adslot_head_html') ? adslot_head_html() : ''; ?>

3插件开发

插件用于扩展功能：挂内容钩子、加前台虚拟页、挂后台管理页、建自己的数据表。一个插件 = 一个目录 + 一个 JSON 清单。

3.1 目录结构与 plugin.json

插件目录 plugins/{slug}/，主入口默认 main.php（可经清单 main 字段改名），清单文件 plugin.json 字段全表：

完整示例：

{
  "slug": "data_export",
  "title": "数据导出",
  "desc": "一键导出文章与栏目数据。",
  "version": "1.0.0",
  "author": "你的名字",
  "main": "main.php",
  "hooks": ["footer", "admin_menu"],
  "schema": "schema.sql",
  "require": { "php": "7.4", "cms": "1.0.0" },
  "features": ["CSV 导出", "后台一键操作"]
}

3.2 入口与生命周期

框架每个请求会对所有已启用插件 require_once plugins/{slug}/main.php（按后台排序加载，单个插件抛异常不会拖垮整站）。main.php 的顶层代码就是注册点：

<?php
/** 数据导出插件入口 */
defined('ROOT') || exit('Access denied');

plugin_on('footer', 'myplg_footer_html');       // 挂钩子：返回字符串
plugin_mod('datadown', 'myplg_page');            // 注册虚拟页 ?mod=datadown
myplg_ensure_tables();                           // 幂等建表（推荐 CREATE TABLE IF NOT EXISTS）

function myplg_footer_html() {
    return '<div id="myplg-foot">...</div>';    // 返回字符串，勿 echo
}
function myplg_page($mod) { ... 自行输出并 exit; }

• 函数名一律带插件 slug 前缀（如 myplg_），避免与其他插件 / 框架函数撞名。
• 需要区分前台后台时，用 defined('DK_ADMIN') 或检查当前脚本路径判断。
• plugin_dir($slug) 取插件绝对路径、plugin_url($slug, $file) 取插件资源网址。

3.3 钩子清单

注册：plugin_on($name, $cb)；触发：plugin_fire($name, $payload)（返回各回调返回值数组）。当前框架提供的钩子：

/* 钩子回调示例：文章保存后同步 */
plugin_on('article_saved', function ($payload) {
    if (($payload['action'] ?? '') !== 'create') return;
    DB::insert('myplg_index', [
        'aid'  => (int) $payload['id'],
        'title' => (string) ($payload['data']['title'] ?? ''),
    ]);
});

3.4 前台虚拟页 ?mod=xxx

插件可注册前台独立页面（框架内置 mod 之外的地址），用户访问 ?mod=datadown 时插件完全接管输出：

plugin_mod('datadown', 'myplg_page');   // mod 名仅小写字母数字下划线

function myplg_page($mod) {
    /* 需要模板壳可 include，并自行 exit */
    include template_path('header.php');
    echo '<div class="container">插件页面内容</div>';
    include template_path('footer.php');
    exit;
}

3.5 后台管理页

插件目录内的 admin.php、admin_config.php、admin_setting.php 及其余 admin_*.php（不含 admin_*_api.php）会被后台「插件管理」自动发现，出现「管理」按钮。页面经统一网关渲染：

admin/plugin_page.php?slug=data_export&f=admin.php

网关已做：登录校验、POST CSRF 校验、插件启用状态校验、文件名防穿越。页面内规则：

• 入口网址用 plugin_admin_page_url('data_export', 'admin.php') 生成，不要手拼。
• 所有 POST 表单必须带：<input type="hidden" name="_csrf" value="<?php echo e(csrf_token()); ?>">。
• 可定义 $pageTitle 覆盖页标题（默认取 plugin.json 的 title）。
• 子页分发参数用 p（&p=slots），f 被网关占用。

<?php
/** 插件后台页样例（admin.php，分发器模式） */
defined('ROOT') || exit('Access denied');
$selfUrl = plugin_admin_page_url('data_export', 'admin.php');
$p = get('p', 'list');
if ($p === 'list')        require __DIR__ . '/admin_list.php';
elseif ($p === 'export') require __DIR__ . '/admin_export.php';

3.6 数据表

表名必须以 {数据库前缀}{插件slug}_ 开头，这是卸载清理与隔离的依据。建表 SQL 写在清单 schema 指向的文件里（如 schema.sql），安装 / 覆盖升级时自动执行：

-- schema.sql：仅允许 CREATE TABLE / ALTER TABLE，表名前缀用 {{prefix}} 占位
CREATE TABLE IF NOT EXISTS `{{prefix}}data_export_logs` (
  `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `aid` INT UNSIGNED NOT NULL DEFAULT 0,
  `created_at` INT UNSIGNED NOT NULL DEFAULT 0,
  PRIMARY KEY (`id`),
  KEY `idx_aid` (`aid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

框架数据库类常用方法：

3.7 启用、停用与卸载

• 启用前自动语法预检：后台对整个插件目录跑 php -l，有语法错误直接拒绝启用——发布前请自查。
• 停用：status=0，主入口不再被加载；模板等处直接调插件函数会白屏，所以调用方要按 2.7 的守卫写法防御。
• 熔断：站点存在 plugins/.disabled 文件时所有插件一律不加载（排障开关）。
• 卸载：删除插件目录与注册行；勾选清理数据时 DROP 所有 {前缀}{slug}_ 开头的表——所以表名前缀必须严格，否则清理不到或误删别人数据。

4内置插件调用

系统随主程序分发六个内置插件：广告位（adslot）、用户中心（member）、VIP 会员（vip）、下载站（download）、接口对接 CPS（cps_connect）、APP 应用下载导航（appnav）。内置插件在 plugin.json 声明 "builtin": true，首次访问自动登记且默认停用，站长在后台按需启用；可停用、不可卸载，数据表始终保留（建表由插件自愈函数保证，不依赖安装流程）。模板调用它们的函数前，先按 2.7 的守卫写法确认函数存在。

本手册详述其中三个最常被模板调用的插件（adslot / appnav / cps_connect）；member、vip、download 的前台函数（如 member_uid()、vip_is_vip()）用法见各插件目录内的 README。另有网址导航 nav_grabber（4.4）为市场分发插件，调用方式一并收录。

4.1 广告位 adslot

全站广告统一管理：模板只声明广告位标识，投放内容全部由站长在后台配置，换广告、换图、调时间窗都不需要改模板。支持 8 种广告形式：

弹窗与底部固定条由页面底部钩子全站自动注入，后台建好即生效，模板无需任何改动。

模板调用

<?php adslot('home_banner'); ?>                             // 直接输出（最常用）
<?php echo adslot_html('home_banner'); ?>                 // 返回字符串，便于判断空
<?php echo adslot_inject($art['content'], 'art_inline'); ?> // 文中插入：输出处理后的正文

// 信息流：取出广告内容，自行混进文章列表（插入间隔读后台配置）
$feeds = adslot_feed('list_feed');
$slot  = adslot_slot_by_code('list_feed');
$every = $slot ? max(1, (int) as_cfg(adslot_config($slot), 'every', 5)) : 5;
foreach ($list as $i => $a) {
    // … 原有列表项输出 …
    if ($feeds && ($i + 1) % $every === 0) {
        $item = array_shift($feeds);
        echo adslot_render_item($item, $slot, ['mode' => 'feed']);
    }
}

虚拟页接入

?mod=nav 这类插件自治渲染页不经过框架在 </head> 与 </body> 前的头尾注入，只靠钩子会出现「有广告没样式」。插件提供两个「同请求只输出一次」的函数，模板在页头页尾各调一次即可，与钩子自动去重：

// header.php 的 </head> 前
<?php echo function_exists('adslot_head_html') ? adslot_head_html() : ''; ?>
// footer.php 的 </body> 前
<?php echo function_exists('adslot_foot_html') ? adslot_foot_html() : ''; ?>

内置 default 模板已占用的标识

站长后台按标识新建广告位即可直接投放，模板无需改动：

自定义模板的标识可自定，建议同样带模板前缀（如 mytpl_side）避免撞名。曝光按广告进入可视区域计一次，点击走 ?mod=adslot&act=click 计数后 302 跳转，跳转带开放协议白名单。

4.2 APP 应用下载导航 appnav

为应用商店 / 下载导航类模板提供分类与应用数据：分类管理、应用发布（图标 / 名称 / 简介 / 版本 / 多下载链接）、广告位（顶部横幅 + 分类间穿插）、点击统计。本插件不渲染前台页面——只提供 appnav_*() 数据函数，模板取数后自行渲染；前台仅注册一个计数跳转入口 ?mod=appnavgo（点击先计数再 302 到真实地址，真实地址不外露，后台改地址不用改模板）。配套官方模板 apphub（手机端优先）可直接参考。

分类与列表

<?php if (function_exists('appnav_cats')): ?>
<?php
$cats = appnav_cats();                 // 启用中的分类（sort DESC），每行含 app_count
$apps = appnav_apps([                  // 应用列表，每行自动带 links 数组
    'cat_id' => 0,                     // 按分类筛选（0=全部）
    'kw'     => '',                    // 按名称/简介搜索
    'order'  => 'sort',                // sort 权重（默认）| hot 点击量 | new 最新
    'per'    => 24, 'page' => 1,       // 每页数量（≤100）
]);
$app = appnav_app($id);                // 单个应用（含 links）
// 应用行：id / cat_id / name / icon / intro / version / size / hits / sort / status / links
// links 行：id / app_id / title（按钮文字）/ url / hits / sort
?>
<?php endif; ?>

按分类分组（导航首页形态）

$sections = appnav_apps_by_cat(8);      // 每分类取 8 个；0=不限；跳过空分类
foreach ($sections as $s) {
    // $s['cat'] 分类行；$s['apps'] 应用行数组（含 links）
}

下载按钮（计数跳转）

foreach ($app['links'] as $l) {
    echo '<a href="' . e(appnav_go_url($l['id'])) . '">' . e($l['title']) . '</a>';
}
// 点击 → ?mod=appnavgo&lid=xx → 记日志 + 应用/链接双计数 → 302 到真实地址
// 只配一条链接时 links 只有一行，模板自然只渲染一个下载按钮

广告位

$topAds = appnav_ads('top');           // 顶部横幅（多张时模板可轮播）
$midAds = appnav_ads('between');       // 分类间穿插广告（sort DESC）
// 广告行：id / title / image / url / position / cat_id / hits / sort / status
// between 行的 cat_id：>0 = 指定穿插在该分类区块之后；0 = 按顺序穿插
echo '<a href="' . e(appnav_ad_url($ad['id'])) . '"><img src="' . e($ad['image']) . '"></a>';

4.3 接口对接（CPS）cps_connect

电商 CPS 变现的对接工具插件：配置造梦开放平台的 Bearer Token、接口路径与同步热词，一键同步热销榜（high / hot）、热词比价商品、本地生活活动，并管理商品缓存与同步日志。

4.4 网址导航 nav_grabber（市场分发插件）

为导航站、网址大全、工具集类模板提供分类与链接管理，可从目标网址抓取标题、简介、图标与关键词，数据存插件私有表，不占用系统友链表。前台详情页固定为 ?mod=nav&id=X。本插件不再随主程序内置分发，从后台「插件管理 → 插件中心」在线安装。模板调用：

$cats    = ng_get_cats(true);              // 全部启用分类（含 item_count 链接数）
$cat     = ng_get_cat_by_slug('tools');    // 按别名取分类
$items   = ng_get_items($cat['id'], 24);   // 取分类下的链接
$results = ng_search_items('GitHub', 30);  // 按名称 / 简介 / 标签搜索
$detail  = ng_detail_url($id);             // 详情页地址
$logo    = $item['logo'] ?: ng_logo_fallback($item['name']); // 无图标时首字母占位图
if (!ng_safe_url($url)) { /* 拒绝不安全的提交地址 */ }

插件停用后以上函数不存在，模板调用前先 function_exists('ng_get_cats') 判断，或按 2.7 守卫写法手动 require 插件核心文件。配套演示模板 navhub 含首页、分类页、搜索页、详情页与 404 页，可直接参考。

5上架应用中心

5.1 上架流程

资源从开发到出现在市场的完整链路：

1. 本地开发调试：资源放主程序 templates/{slug}/ 或 plugins/{slug}/，切后台模板 / 启用插件实测。
2. 放入市场源：完整拷贝到 market/source/templates/{slug}/（或 source/plugins/{slug}/）。
3. 登记清单：在 market/tools/manifest.php 的对应数组里登记 slug 条目（标题、描述、分类、详情富文本、价格等）。
4. 打包上架：运营方执行打包工具生成 zip 并入库：

   php market/tools/publish.php            # 全部资源重新打包上架
   php market/tools/publish.php tpl        # 仅模板
   php market/tools/publish.php tpl corporate,gov   # 指定 slug
   php market/tools/publish.php --list     # 只查看清单
   php market/tools/publish.php --dry      # 试运行不落库

5. 审核发布：上架后经运营后台审核，通过即在市场前台展示，站长从后台「模板市场 / 插件中心」一键在线安装。

manifest.php 条目字段（市场侧资料，与包内 JSON 清单二者缺一回退）：

5.2 打包规则（安装端强校验）

• zip 内以 {slug}/ 为唯一根目录（也支持外层多包一层目录，安装端会自动定位清单文件）。
• 插件包必须含清单声明的主入口文件；模板包必须含 7 个必需页面文件与含 slug 的 template.json。
• 扩展名白名单：php / html / css / js / json / txt / md / xml / sql / png / jpg / jpeg / gif / svg / webp / ico / eot / ttf / woff / woff2 / map。
• 单文件 ≤ 5MB，单包 ≤ 20MB；隐藏文件（. 开头）与 .git 等版本库目录自动剔除。
• 解压全程路径穿越防护；PHP 文件在安装 / 启用前会做全量语法预检。

5.3 免费与付费资源

清单里 require_level 留空即免费资源，站长一键安装无任何限制。

require_level 非空即付费资源，打包时会自动在入口文件注入域名授权校验（license-guard.php）：

• 站长安装后，资源首次运行时向应用中心核验「当前站点域名是否已登记授权」。
• 核验结果带签名缓存 15 天，断网宽限 45 天；前台访客不受任何影响（完全静默）。
• 未授权仅在站长后台「模板管理 / 插件管理」页显示风险徽标，并提供「验证授权」按钮联网复查；站长可到授权中心免费登记域名。

5.4 上架自检清单

• slug 合规（仅字母数字下划线连字符），且市场内无重名资源。
• 必需文件齐全：模板 7 件套 + 含 slug 的 template.json；插件 main.php + plugin.json。
• 全部 PHP 文件本地 php -l 通过（否则安装 / 启用被拒）。
• 配置键、函数名、数据表均带自己的 slug 前缀，无冲突。
• 模板页面没有手动 include header / footer；SEO 分支写在 header.php；动态输出全部 e()。
• 插件 POST 表单带 _csrf；SQL 全占位符传参；删除数据禁止 _ / % 模糊匹配。
• 预览图就位（目录内 preview.svg 或 preview.png，缺失会生成占位图）。
• manifest.php 已登记条目，分类正确，详情富文本只用了允许标签。