跳到主要内容
万能墙开放平台
插件开发教程

SDK 函数速查(由核心契约生成)

全部内容基于万能墙真实的插件平台(清单 + 钩子 + 接口 + 后台页 + 数据 + 定时任务),示例可直接复制运行。

平台提供的函数(全部可用,不需要引入任何文件)

这些函数在插件加载时就已经就绪,直接调用即可。完整签名与示例也可以用 GET https://wall.lhuiye.cn/api?action=plugin_contract&section=sdk 拉取。

钩子

addAction()

  • 签名:addAction(string $hook, callable $cb, int $priority = 10): bool
  • 作用:监听一个动作(事件)。
  • 返回:bool
  • 起始版本:1.0.0
php
addAction('post_created', function ($postId, $userId, $content) { /* ... */ });

addFilter()

  • 签名:addFilter(string $hook, callable $cb, int $priority = 10): bool
  • 作用:接管一个过滤器;回调必须把(可能改过的)值 return 回去。
  • 返回:bool
  • 起始版本:1.0.0
php
addFilter('post_card_html', function ($html, $post, $comments) { return $html . '<i>★</i>'; });

applyFilters()

  • 签名:applyFilters(string $hook, mixed $value, ...$args): mixed
  • 作用:触发过滤器(插件也可以定义自己的钩子给别的插件用)。
  • 返回:过滤后的值
  • 起始版本:1.0.0
php
$out = applyFilters('my_plugin_row', $row, $postId);

doAction()

  • 签名:doAction(string $hook, ...$args): void
  • 作用:触发动作(供别的插件监听)。
  • 返回:void
  • 起始版本:1.0.0
php
doAction('my_plugin_done', $userId);

registerHookDoc()

  • 签名:registerHookDoc(string $hook, string $type, string $desc): void
  • 作用:给自定义钩子写说明(type: 'action' | 'filter'),后台钩子清单会显示。
  • 返回:void
  • 起始版本:1.0.0
php
registerHookDoc('my_plugin_row', 'filter', '单行数据,可改字段');

接口

registerApiRoute()

  • 签名:registerApiRoute(string $action, array $opts, callable $handler): bool
  • 作用:注册接口。opts:method(GET|POST|ANY)、auth(none|login)、admin(bool)、module(模块键)、desc、params(array)、no_params(bool)。
  • 返回:bool
  • 起始版本:1.0.0
php
registerApiRoute('my_stats', [
    'method' => 'GET', 'auth' => 'login', 'desc' => '我的统计',
    'params' => ['days' => 'int 统计天数,默认 7'],
], function (array $ctx) {
    // $ctx: db / user_id / method / query(GET) / input(POST) / json / ip
    return ['days' => (int)($ctx['query']['days'] ?? 7)];
});

apiPluginRoute()

  • 签名:apiPluginRoute(string $action): ?array
  • 作用:查询某个接口是否由插件注册(一般不用自己调)。
  • 返回:array|null
  • 起始版本:1.0.0

后台

registerAdminPage()

  • 签名:registerAdminPage(string $slug, array $opts, callable $renderer): bool
  • 作用:注册后台页面;需要 admin_ui 能力。opts:title、icon(fa-* 类名)、desc、perm。renderer 里自行 echo HTML。
  • 返回:bool
  • 起始版本:1.0.0
php
registerAdminPage('my_plugin', ['title' => '我的插件', 'icon' => 'fa-puzzle-piece'], function () {
    echo '<div class="card">你好</div>';
});

前台

registerFrontView()

  • 签名:registerFrontView(string $slug, string $view, callable $renderer): bool
  • 作用:注册前台视图;需要 front_ui 能力。renderer(array $ctx): ?string,返回字符串直接输出,返回 null 表示自己 echo。
  • 返回:bool
  • 起始版本:1.0.0
php
registerFrontView('my_plugin', 'index', function (array $ctx) {
    return '<h1>我的插件页面</h1>';
});

addShortcode()

  • 签名:addShortcode(string $tag, callable $cb): bool
  • 作用:注册短代码,正文里写 [tag attr="x"]内容[/tag];回调签名 function (array $attrs, string $inner): string。
  • 返回:bool
  • 起始版本:1.0.0
php
addShortcode('hello', function (array $attrs, string $inner) {
    return '<b>' . htmlspecialchars($attrs['name'] ?? $inner, ENT_QUOTES, 'UTF-8') . '</b>';
});

pluginRenderArea()

  • 签名:pluginRenderArea(string $area, array $payload = []): string
  • 作用:取某个渲染区域的 HTML(area: head / body_top / footer / nav_extra)。
  • 返回:string
  • 起始版本:1.0.0
php
echo pluginRenderArea('footer', ['page' => 'index']);

pluginRenderAreaFor()

  • 签名:pluginRenderAreaFor(string $area, array $payload = [], string $requiredCapability = 'front_ui'): string
  • 作用:取某个渲染区域的 HTML,且只接受声明了指定能力的插件(默认 front_ui)。用于 profile_cards / settings_cards 这类需要能力门控与私有上下文的用户面板槽位;无法确定归属的注入一律不执行。
  • 返回:string
  • 起始版本:1.2.0
php
$html = pluginRenderAreaFor('profile_cards', ['user_id' => $uid, 'is_self' => true, 'page' => 'profile']);
if ($html !== '') echo $html;

pluginAssetUrl()

  • 签名:pluginAssetUrl(string $slug, string $rel): string
  • 作用:生成插件静态资源地址(自动带版本号);只允许 assets/ 目录。
  • 返回:string
  • 起始版本:1.0.1
php
echo '<link rel="stylesheet" href="' . pluginAssetUrl('my_plugin', 'assets/app.css') . '">';

数据

pluginUserMetaGet()

  • 签名:pluginUserMetaGet(string $slug, int $userId, string $key, mixed $default = null): mixed
  • 作用:读「本插件 + 本用户」的一个键值(平台公共表 plugin_user_meta,插件不用自己建表)。键不存在返回 $default;键存在但值为空串时返回空串。$key 只允许 [a-z0-9_\-](超长截断到 64 字符)。
  • 返回:mixed
  • 起始版本:1.2.0
php
$note = pluginUserMetaGet('my_plugin', $userId, 'note', '');

pluginUserMetaSet()

  • 签名:pluginUserMetaSet(string $slug, int $userId, string $key, mixed $value): bool
  • 作用:写/删「本插件 + 本用户」的一个键值:$value === null 删除该键,否则写入(单值最多 2000 字符,超出截断)。$userId 必须 > 0,$slug 必须合法,$key 只允许 [a-z0-9_\-]。
  • 返回:bool
  • 起始版本:1.2.0
php
registerApiRoute('my_save', ['method' => 'POST', 'auth' => 'login', 'params' => ['note' => 'string']], function (array $ctx) {
    return ['success' => pluginUserMetaSet('my_plugin', (int)$ctx['user_id'], 'note', (string)($ctx['input']['note'] ?? ''))];
});

pluginUserMetaAll()

  • 签名:pluginUserMetaAll(string $slug, int $userId): array
  • 作用:读「本插件 + 本用户」的全部键值(meta_key => meta_value 关联数组)。
  • 返回:array
  • 起始版本:1.2.0
php
$all = pluginUserMetaAll('my_plugin', $userId);

pluginTableName()

  • 签名:pluginTableName(string $slug, string $suffix = ''): string
  • 作用:生成自己的表名:plugin_<slug>[_<suffix>]。第二个参数是本轮新增,之前会被忽略。
  • 返回:string
  • 起始版本:1.0.1
php
$table = pluginTableName('my_plugin', 'marks');

pluginCreateTable()

  • 签名:pluginCreateTable(string $slug, string $suffix, string $columnsSql): bool
  • 作用:建表(幂等,用 CREATE TABLE IF NOT EXISTS);列定义按 SQLite 语法写。
  • 返回:bool
  • 起始版本:1.0.0
php
pluginCreateTable('my_plugin', 'marks', 'post_id INTEGER, user_id INTEGER, created_at TEXT');

getDB()

  • 签名:getDB(): PDO
  • 作用:站点数据库连接(PDO/SQLite,已配置 WAL 与 busy_timeout)。只读核心表没问题,写入核心表请谨慎。
  • 返回:PDO
  • 起始版本:1.0.0
php
$db = getDB();
$rows = $db->query('SELECT id, content FROM posts ORDER BY id DESC LIMIT 5')->fetchAll(PDO::FETCH_ASSOC);

设置

pluginSetting()

  • 签名:pluginSetting(string $slug, ?string $key = null, mixed $default = null): mixed
  • 作用:读设置:传 key 读一项,不传 key 读全部(含清单里声明的默认值)。
  • 返回:mixed
  • 起始版本:1.0.0
php
$on = pluginSetting('my_plugin', 'enabled', '1') === '1';

pluginSaveSettings()

  • 签名:pluginSaveSettings(string $slug, array $kv): bool
  • 作用:写设置(键值对)。
  • 返回:bool
  • 起始版本:1.0.0
php
pluginSaveSettings('my_plugin', ['enabled' => '1']);

pluginSettingsWithDefaults()

  • 签名:pluginSettingsWithDefaults(string $slug): array
  • 作用:取「清单默认值 + 已存值」的合并结果,老版本升级后新加的设置项不会读到 null。
  • 返回:array
  • 起始版本:1.0.1

pluginResetSettings()

  • 签名:pluginResetSettings(string $slug): bool
  • 作用:把设置恢复为清单里的默认值。
  • 返回:bool
  • 起始版本:1.0.1
php
pluginResetSettings('my_plugin');

pluginClearSettings()

  • 签名:pluginClearSettings(string $slug): bool
  • 作用:清空设置(卸载时用)。
  • 返回:bool
  • 起始版本:1.0.0

文件

pluginUploadDir()

  • 签名:pluginUploadDir(): string
  • 作用:插件上传目录(绝对路径,已存在且可写);保存文件后建议只记相对路径。
  • 返回:string
  • 起始版本:1.0.0
php
$dst = pluginUploadDir() . '/' . $slug . '_' . time() . '.png';

网络

pluginHttp()

  • 签名:pluginHttp(string $slug, string $url, array $opts = []): array
  • 作用:受控的外部请求(需要 http 能力):opts 支持 method / body / headers / timeout / json。
  • 返回:['ok','status','body','error']
  • 起始版本:1.0.0
php
$r = pluginHttp('my_plugin', 'https://api.example.com/ping', ['timeout' => 5]);
if ($r['ok']) { $data = json_decode($r['body'], true); }

诊断

pluginLog()

  • 签名:pluginLog(string $slug, string $level, string $message): void
  • 作用:写插件日志(level: info / warn / error),后台插件详情可读。
  • 返回:void
  • 起始版本:1.0.0
php
pluginLog('my_plugin', 'warn', '上游接口超时,已跳过');

pluginLogs()

  • 签名:pluginLogs(string $slug, int $limit = 50): array
  • 作用:读自己的日志(排障用)。
  • 返回:array
  • 起始版本:1.0.0

pluginCan()

  • 签名:pluginCan(string $slug, string $cap): bool
  • 作用:判断自己是否声明了某项能力。
  • 返回:bool
  • 起始版本:1.0.0
php
if (pluginCan('my_plugin', 'mail')) { /* ... */ }

pluginManifest()

  • 签名:pluginManifest(string $slug): ?array
  • 作用:读自己的清单(含平台解析后的设置项与能力)。
  • 返回:array|null
  • 起始版本:1.0.0

定时任务

registerPluginCron()

  • 签名:registerPluginCron(string $slug, string $key, int $interval, callable $cb): bool
  • 作用:注册定时任务(最小间隔 60 秒,由站点流量驱动;回调签名 function (array $ctx))。
  • 返回:bool
  • 起始版本:1.0.0
php
registerPluginCron('my_plugin', 'cleanup', 3600, function (array $ctx) {
    // 每小时最多跑一次
});

邮件

sendEmailTracked()

  • 签名:sendEmailTracked(string $to, string $subject, string $html, string $purpose = '', int $userId = 0): array
  • 作用:走站点发件通道发信(需要 mail 能力);成功失败都记入发件台账,失败自动入队重试。
  • 返回:['success','mode'|'error']
  • 起始版本:1.0.1
php
$r = sendEmailTracked($to, '通知', '<p>内容</p>', 'my_plugin', $userId);