平台提供的函数(全部可用,不需要引入任何文件)
这些函数在插件加载时就已经就绪,直接调用即可。完整签名与示例也可以用 GET https://wall.lhuiye.cn/api?action=plugin_contract§ion=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);