文档
开发者指南
核心挂钩和过滤器参考：完整的开发人员指南
核心钩子和过滤器参考
受众： 开发人员 — 需要 PHP / Laravel 知识。
类别： 技术参考 — 集成程序员的技术文档。
你将学到什么
1.Hook系统介绍
PolyCMS 使用类似于 WordPress 的 Hook/Filter 系统，原生构建在 Laravel 上：
Action (Hook::doAction)：运行副作用（记录、发送电子邮件、同步数据）。无需返回。Filter (Hook::applyFilters)：获取一个值，编辑，然后强制返回 调整后的值。
基本语法
use App\Facades\Hook;
// Sign up for Action
Hook::addAction('order_completed', function ($order) {
Mail::to($order->user)->send(new OrderCompletedMail($order));
}, priority: 10);
// Sign up for Filter
Hook::addFilter('post.default_image', function (?string $imageUrl, $post) {
if ($post?->categories->contains('slug', 'news')) {
return '/images/news-default.jpg';
}
return $imageUrl;
}, priority: 10);
2. 内容和帖子
过滤器
钩
参数
描述
post.default_image$imageUrl, $context文章没有特色图片时的默认图片
post.frontend_url$url, $post自定义帖子的公共 URL
post.content.render$html, $post返回 API 之前过滤 HTML 内容
post.query.builder$query, $request编辑帖子列表的 Eloquent 查询
category.frontend_url$url, $category自定义您的类别的公共 URL
content.render.blocks$blocks渲染前过滤块数组
content.render.html$html, $blocks过滤最终输出 HTML
content.render.block.{type}$html, $block渲染或覆盖特定块类型
行动
钩
参数
描述
tag.saved$tag, $context创建/更新标签后
tag.deleted$tag, $context标签删除后
category.saved$category, $context创建/更新类别后
category.deleted$category, $context类别删除后
实际用例
UC1 — 按类别划分的代表性图像： 当文章未设置特色图像时，新闻网站希望每个类别都有自己的默认图像：
Hook::addFilter('post.default_image', function (?string $url, $post) {
if ($post?->categories->contains('slug', 'tech')) return '/images/defaults/tech.jpg';
if ($post?->categories->contains('slug', 'lifestyle')) return '/images/defaults/lifestyle.jpg';
return $url; // fallback admin setting
});
UC2 — Wiki URL： 文档主题想要将帖子 URL 从 /posts/slug 移动到 /docs/slug：
Hook::addFilter('post.frontend_url', function ($url, $post) {
return ($post->type === 'wiki') ? '/docs/' . $post->slug : $url;
});
UC3 — 自动插入广告： 广告模块希望在文章内容第3段后插入横幅：
Hook::addFilter('content.render.html', function (string $html) {
$adBanner = '<div class=\"ad-inline\">Advertisement</div>';
$parts = explode('</p>', $html, 4);
if (count($parts) > 3) {
$parts[2] .= '</p>' . $adBanner;
return implode('</p>', $parts);
}
return $html;
});
3.媒体库
过滤器
钩
参数
描述
media.upload.file$file, $data处理前编辑文件
media.upload.data$data, $file编辑上传元数据
media.create.data$mediaData, $file保存DB前调整记录数据
media.delete.should$shouldDelete，$mediaGate：返回“false”以防止删除
media.url$url, $media重写 URL (e.g.CDN)
行动
钩
参数
描述
media.uploaded$media, $file, $data上传成功后
media.deleting$media删除之前
media.deleted$media删除后
实际用例
UC1 — CDN 重写： 集成 Cloudflare R2/S3，自动将媒体 URL 转换为 CDN 域：
Hook::addFilter('media.url', function (string $url, $media) {
return str_replace('/storage/', 'https://cdn.mysite.com/', $url);
});
UC2 — 保护重要文件： 防止删除用作站点徽标的图像：
Hook::addFilter('media.delete.should', function (bool $allow, $media) {
$logoUrl = get_option('site_logo', null, 'general');
return ($media->url === $logoUrl) ? false : $allow;
});
UC3 — 上传时自动优化： 从上传的图像自动创建 WebP：
Hook::addAction('media.uploaded', function ($media, $file) {
if (str_starts_with($media->mime_type, 'image/')) {
dispatch(new ConvertToWebpJob($media));
}
});
4. 电子商务 — 订单和退款
行动
钩
参数
描述
order_status_updated$order, $oldStatus, $newStatus当订单状态发生变化时
order_completed$order订单何时完成
order.refund.processing$order, $validated退款前
order.refund.completed$order, $result退款成功后
order.refund.succeeded$order, $result, $validated, $userIdAPI退款成功
order.refund.failed$order, $validated, $exception, $userIdAPI退款失败
过滤器
钩
参数
描述
order.refund.preview.result$preview, $order, $input调整退款预览
实际用例
UC1 — 有新订单时电报通知：
Hook::addAction('order_status_updated', function ($order, $old, $new) {
if ($old === 'pending' && $new === 'processing') {
TelegramBot::send("Order #{$order->code} has been confirmed!");
}
});
UC2 — 完成申请后赚取忠诚度积分：
Hook::addAction('order_completed', function ($order) {
if ($order->user_id) {
$points = (int) floor($order->total / 10000); // 1 point per 10k
LoyaltyService::addPoints($order->user_id, $points, "Order #{$order->code}");
}
});
UC3——退款失败时记录审核日志：
Hook::addAction('order.refund.failed', function ($order, $data, $exception, $userId) {
AuditLog::create([
'action' => 'refund_failed',
'order_id' => $order->id,
'user_id' => $userId,
'reason' => $exception->getMessage(),
]);
});
5. 电子商务 — 购物车、运输、税收、库存
过滤器
钩
参数
描述
cart.totals$totals, $cart调整购物车总数
shipping.calculate_cost$cost, $method, $cart覆盖运费
shipping.available_methods$methods, $address, $cart过滤运输方式
tax.calculated$result, $subtotal, $address覆盖税收计算结果
inventory.is_stockable_product$default, $product, $context通过库存管理识别产品
review.can_submit$allowed, $user, $productGate：允许评论吗？
行动
钩
参数
描述
cart.item.added$item, $cart将商品添加到购物车后
cart.item.updated$item, $oldQty, $newQty更新数量后
cart.item.removed$item, $cart从购物车中删除商品后
cart.cleared$cart删除整个购物车后
cart.merged$userCart, $guestCart将访客购物车合并到用户购物车时
review.submitted$review提交评论后
review.approved$review看完评论后
review.rejected$review驳回审核后
实际用例
UC1 — 订单金额超过 50 万免运费：
Hook::addFilter('shipping.calculate_cost', function ($cost, $method, $cart) {
$subtotal = collect($cart->items)->sum(fn($i) => $i->price * $i->quantity);
return ($subtotal >= 500000) ? 0 : $cost;
});
UC2 — 如果您尚未购买，则阻止评论：
Hook::addFilter('review.can_submit', function (bool $allowed, $user, $product) {
$hasPurchased = Order::where('user_id', $user->id)
->where('status', 'completed')
->whereHas('items', fn($q) => $q->where('product_id', $product->id))
->exists();
return $hasPurchased;
});
UC3 — 添加购物车时的 Facebook 像素跟踪：
Hook::addAction('cart.item.added', function ($item, $cart) {
session()->push('fb_pixel_events', [
'event' => 'AddToCart',
'product_id' => $item->product_id,
'value' => $item->price,
]);
});
6. 电子商务——支付网关
过滤器
钩
参数
描述
payment.gateway.config_schema$schema, $gateway展开网关配置架构
用例：为银行转账网关添加“分行代码”字段：
Hook::addFilter('payment.gateway.config_schema', function ($schema, $gateway) {
if ($gateway->code === 'bank_transfer') {
$schema['branch_code'] = [
'type' => 'text', 'label' => 'Branch code', 'required' => false,
];
}
return $schema;
});
7. 主题和外观
过滤器
钩
参数
描述
theme.view.data$data, $viewName将数据注入任何视图
theme.template.resolve$viewName, $templateTheme, $entityType, $entity覆盖 Blade 视图的渲染
theme.template.registry$templates, $viewType注册新页面模板
theme.options.values$options过滤主题选项
theme.options.css_vars$cssVars, $themeOptionValues调整CSS自定义属性
theme.breadcrumbs.post$breadcrumbs, $post编辑文章面包屑
theme.breadcrumbs.product$breadcrumbs, $product编辑产品面包屑
theme.show_page_header$show, $page隐藏/显示页眉
frontend.topbar.banners$banners注入广告横幅
themes.list$themes过滤管理主题列表
行动
钩
参数
描述
theme.activated$theme当主主题加载时
theme.main.changed$theme, $oldMainTheme当改变主题
theme.installing$file处理 ZIP 主题之前
theme.activating$slug, $type, $mode激活主题之前
theme.deactivating$slug停用主题之前
theme.deleting$theme删除主题之前
cms_head（无） <head> 中的输出挂钩
实际用例
UC1 — 来自模块的全站促销横幅：
Hook::addFilter('frontend.topbar.banners', function (array $banners) {
$banners[] = [
'text' => ' Flash Sale — 30% off today!',
'url' => '/sale',
'bg_color' => '#ff4444',
];
return $banners;
});
UC2 — 将 Google Analytics 注入“”：
Hook::addAction('cms_head', function () {
$ga = get_option('google_analytics_id', null, 'seo');
if ($ga) {
echo "<script async src='https://www.googletagmanager.com/gtag/js?id={$ga}'></script>";
}
});
UC3 — 为博客页面注入侧边栏数据：
Hook::addFilter('theme.view.data', function ($data, $viewName) {
if ($viewName === 'posts.index') {
$data['popular_posts'] = Post::orderBy('views', 'desc')->limit(5)->get();
}
return $data;
});
8. 设置和配置
过滤器
钩
参数
描述
settings.defaults$defaults, $settingsService扩展/覆盖设置定义
settings.media.drivers$drivers注册新的存储驱动程序
settings.permalinks.structure$structure, $settingsService调整永久链接结构
行动
钩
参数
描述
setting.updating$key, $value, $group, $type保存设置之前
settings.saved$payload保存设置后
实际用例
UC1 — 模块在设置页面上注册各个设置：
Hook::addFilter('settings.defaults', function ($defaults) {
$defaults['mymodule'] = [
'mymodule_api_key' => [
'key' => 'mymodule_api_key', 'value' => '', 'type' => 'text',
'label' => 'API Key', 'description' => 'Enter your API key',
],
];
return $defaults;
});
UC2 — 更新永久链接时清除缓存：
Hook::addAction('settings.saved', function ($payload) {
if (($payload['group'] ?? '') === 'permalinks') {
Artisan::call('route:clear');
Cache::tags('routes')->flush();
}
});
9. 用户、角色和身份验证
过滤器
钩
参数
描述
user.resource.to_array$data, $user, $request展开用户 API 响应
auth.login.pre_token$response, $user, $request拦截登录（用于 2FA）
行动
钩
参数
描述
user.creating / user.updating / user.deleting$user|$dataCRUD 生命周期
role.creating / role.updating / role.deleting / role.cloning$role|$dataCRUD 生命周期
实际用例
UC1 — 管理员所需的 2FA：
Hook::addFilter('auth.login.pre_token', function ($response, $user, $request) {
if ($user->hasRole('admin') && !$request->filled('otp_code')) {
return response()->json(['requires_2fa' => true, 'user_id' => $user->id], 403);
}
return $response; // null = continue creating tokens
});
UC2 — 创建用户时发送欢迎电子邮件：
Hook::addAction('user.creating', function ($data) {
// Queued email will be sent after the user is saved
dispatch(new SendWelcomeEmail($data['email'], $data['name']));
});
10. 搜索引擎优化
过滤器
钩
参数
描述
seo.canonical_url$url覆盖规范 URL
seo.site_favicon$iconUrl覆盖图标 URL
用例 — 多语言的规范 URL：
Hook::addFilter('seo.canonical_url', function (string $url) {
$locale = app()->getLocale();
if ($locale !== 'en') {
return url("/{$locale}" . parse_url($url, PHP_URL_PATH));
}
return $url;
});
11. 小部件
过滤器
钩
参数
描述
widget.render.instance$instance渲染前调整小部件实例
widget.render.{widget_type}$widget编辑特定小部件数据
widget.area.render.instances$instances, $area过滤区域中的实例
widget.render.output$html, $instance过滤 HTML 输出小部件
widget.area.render.output$html, $area过滤 HTML 输出区域
widgets.types$widgets过滤小部件类型 admin
行动
钩
参数
描述
widgets.register_types$widgetManager注册新类型小部件
widgets.register_areas$widgetManager注册新的小部件区域
用例 — 注册小部件类型“Store Map”：
Hook::addAction('widgets.register_types', function ($manager) {
$manager->registerType('store_map', [
'label' => 'Store Map',
'description' => 'Google Maps showing store locations',
'fields' => [
'api_key' => ['type' => 'text', 'label' => 'Google Maps API Key'],
'lat' => ['type' => 'text', 'label' => 'Latitude'],
'lng' => ['type' => 'text', 'label' => 'Longitude'],
],
'view' => 'widgets.store-map',
]);
});
12. 管理导航和编辑器
过滤器
钩
参数
描述
topbar.menu.items$items, $request, $user添加/删除前端顶栏项目
topbar.menu.should_show$show, $user切换显示顶栏
admin.editor.panels$panels, $type, $user将自定义面板添加到块编辑器
行动
钩
参数
描述
admin.menu.build（无） 侧边栏管理菜单何时构建
topbar.menu.context$request, $user当顶栏上下文初始化时
用例 — 模块将菜单项“SEO Score”添加到顶栏：
Hook::addFilter('topbar.menu.items', function (array $items, $request, $user) {
$items[] = [
'key' => 'seo_score',
'label' => 'SEO Score',
'icon' => 'chart-bar',
'url' => '/admin/seo/score',
'position' => 50,
];
return $items;
});
13. 模块
过滤器
钩
参数
描述
module.resource.meta$meta, $moduleData展开元数据模块
modules.list$modulesArray过滤管理模块列表
product.query.builder$query, $request调整产品的 Eloquent 查询
行动
钩
参数
描述
module.activating$moduleKey, $module激活模块之前
module.deactivating$moduleKey, $module停用模块之前
module.deleting$moduleKey, $module删除模块之前
module.installing$uploadedFile安装 ZIP
用例 — 激活模块时运行迁移：
Hook::addAction('module.activating', function ($moduleKey, $module) {
Artisan::call('migrate', [
'--path' => "modules/Polyx/{$moduleKey}/database/migrations",
'--force' => true,
]);
});
14. 系统引导
行动
钩
参数
描述
roles.register_permissions$permissionRegistry注册自定义权限
register_email_templates$emailTemplateManager注册电子邮件模板
layout.register_assets$layoutAssetManager注册布局资源
routes.frontend.register（无） 注册额外的前端路由
用例——私有权限注册模块：
Hook::addAction('roles.register_permissions', function ($registry) {
$registry->register('manage analytics', 'Analytics', 'View and manage analytics dashboard');
$registry->register('export reports', 'Analytics', 'Export analytics reports to CSV');
});
相关文章