Bludit CMS最常用的钩子和内置函数

12月 21, 2025 - 阅读需时: 13 分钟

你想要梳理 Bludit CMS 开发中最常用的钩子（Hooks）和内置函数，这是扩展 Bludit 功能的核心基础。下面我会按「钩子」「核心函数」两大模块，分类整理高频使用的内容，并附上实用示例，方便你直接复用。

一、最常用的钩子（Hooks）

Bludit 的钩子是「事件触发点」，能在不修改核心代码的前提下拦截/扩展系统行为。以下按「使用场景」分类，列出开发中 80% 场景会用到的钩子：

1. 内容生命周期钩子（文章/页面）

钩子名称	触发时机	核心参数	典型用途
`beforePageCreate`	创建文章/页面前	`$args['data']`（提交的表单数据）	内容校验、自动补全字段（如摘要）
`afterPageCreate`	创建文章/页面后	`$args['page']`（页面对象）	同步内容到第三方平台、记录日志
`beforePageSave`	保存文章/页面前	`$args['page']`（页面对象）	过滤敏感内容、自动计算阅读时长
`afterPageSave`	保存文章/页面后	`$args['page']`（页面对象）	更新缓存、推送站内通知
`beforePageDelete`	删除文章/页面前	`$args['pageKey']`（页面唯一标识）	备份待删除内容、校验删除权限

示例：保存文章时自动生成摘要

public function init() {
    $this->addHook('beforePageSave', 'autoGenerateExcerpt');
}

public function autoGenerateExcerpt($args) {
    $page = $args['page'];
    // 如果用户未填写摘要，自动从内容截取150字
    if (empty($page->excerpt())) {
        $content = strip_tags($page->content()); // 去除HTML标签
        $excerpt = mb_substr($content, 0, 150, 'UTF-8') . '...';
        $page->setExcerpt($excerpt);
    }
}

2. 页面渲染钩子（前端/后台）

钩子名称	触发时机	核心参数	典型用途
`beforeRender`	所有页面渲染前	`$args['where']`（渲染位置：front/admin）、`$args['content']`（待渲染内容）	注入全局变量、SEO 优化（加关键词）
`afterRender`	所有页面渲染后	`$args['content']`（渲染后的HTML）	替换内容、添加统计代码（如百度统计）
`adminHead`	后台页面 `<head>` 渲染时	无（直接输出HTML）	加载自定义CSS/JS（如新增后台按钮样式）
`siteHead`	前端页面 `<head>` 渲染时	无（直接输出HTML）	加载前端样式、引入CDN资源
`afterPageRender`	单篇文章/页面渲染后	`$args['content']`（页面HTML）	添加版权信息、相关文章推荐

示例：前端页面底部添加统计代码

public function init() {
    $this->addHook('afterRender', 'addAnalytics');
}

public function addAnalytics($args) {
    // 仅在前端页面生效
    if ($args['where'] == 'front') {
        $analyticsCode = '<script src="https://hm.baidu.com/hm.js?你的ID"></script>';
        $args['content'] = str_replace('</body>', $analyticsCode . '</body>', $args['content']);
    }
    return $args;
}

3. 用户操作钩子

钩子名称	触发时机	核心参数	典型用途
`loginSuccess`	用户登录成功后	`$args['username']`（用户名）	记录登录日志、多租户验证
`loginFailure`	用户登录失败后	`$args['username']`（用户名）	防暴力破解（限制登录次数）
`afterUserCreate`	创建用户后	`$args['user']`（用户对象）	发送欢迎邮件、初始化用户权限

4. 系统初始化钩子

钩子名称	触发时机	核心参数	典型用途
`init`	插件初始化时（替代类的init方法）	无	注册路由、初始化配置
`routerBefore`	路由解析前	`$args['uri']`（当前访问URI）	自定义路由、URL重写

二、最常用的内置函数/对象方法

Bludit 提供了丰富的内置对象和方法，用于快速获取/操作数据，以下按「数据类型」分类整理高频用法：

1. 站点全局信息（$site 对象）

方法	作用	示例
`$site->title()`	获取站点标题	`echo $site->title(); // 输出博客名称`
`$site->description()`	获取站点描述	用于SEO元标签
`$site->url()`	获取站点根URL	`echo $site->url() . '/about'; // 拼接关于页URL`
`$site->language()`	获取站点语言	`if ($site->language() == 'zh') { ... }`
`$site->custom($key)`	获取站点自定义字段	`$site->custom('phone'); // 获取站点联系电话`

2. 文章/页面操作（$page/$posts 对象）

（1）单篇文章/页面（$page 对象）

方法	作用	示例
`$page->title()`	获取标题
`$page->content()`	获取完整内容
`$page->excerpt($length)`	获取摘要（指定长度）	`$page->excerpt(200); // 200字摘要`
`$page->permalink()`	获取永久链接
`$page->date($format)`	获取发布时间（自定义格式）	`$page->date('Y-m-d H:i');`
`$page->category()`	获取分类名称
`$page->tags()`	获取标签数组	`foreach($page->tags() as $tag) { ... }`
`$page->custom($key)`	获取自定义字段	`$page->custom('readingTime'); // 阅读时长`
`$page->setCustom($key, $value)`	设置自定义字段	插件中保存自定义数据

（2）文章列表（Posts 类）

方法	作用	示例
`Posts::getList($page, $amount, $orderBy)`	获取文章列表	`$posts = Posts::getList(0, 10, 'date'); // 最新10篇`
`Posts::getByCategory($category)`	按分类筛选	`$posts = Posts::getByCategory('技术');`
`Posts::count()`	获取总文章数

3. 用户操作（$user/Users 类）

方法	作用	示例
`$user->username()`	获取当前登录用户名
`$user->role()`	获取用户角色（admin/editor）	`if ($user->role() == 'admin') { ... }`
`Users::get($username)`	获取指定用户对象

4. 工具类函数

函数	作用	示例
`sanitize($string)`	过滤XSS、特殊字符	`$safeStr = sanitize($_POST['content']);`
`permalink($string)`	生成URL友好的字符串	`$slug = permalink('Bludit CMS教程'); // bludit-cms教程`
`json_encode_pretty($data)`	格式化JSON输出	保存配置文件时使用
`buildHTTPQuery($params)`	拼接URL参数	`$url = $site->url() . '?' . buildHTTPQuery(['page' => 1]);`

5. 自定义路由（插件中）

// 注册路由：https://你的站点.com/api/posts
public function init() {
    $this->addRoute('api/posts', 'handleApiPosts');
}

// 处理路由请求
public function handleApiPosts() {
    header('Content-Type: application/json');
    $posts = Posts::getList(0, 10);
    $data = [];
    foreach ($posts as $post) {
        $data[] = [
            'title' => $post->title(),
            'url' => $post->permalink()
        ];
    }
    echo json_encode($data, JSON_UNESCAPED_UNICODE);
    exit; // 终止默认渲染
}

总结

核心钩子关键点

内容相关逻辑优先用 before/afterPageSave，能覆盖大部分文章/页面定制需求；
前端样式/脚本注入用 siteHead/afterRender，后台定制用 adminHead；
用户权限/登录控制用 loginSuccess/loginFailure。

核心函数关键点

获取/设置数据优先用内置对象（$site/$page/$user），避免直接操作文件；
用户输入必须用 sanitize() 过滤，防止XSS漏洞；
插件中自定义API/路由用 addRoute()，是扩展Bludit接口能力的核心方式。

如果需要针对某个具体场景（比如开发评论插件、实现内容搜索）的钩子+函数组合示例，我可以补充完整代码。