PolyCMS cho RISE CRM cung cấp hệ thống Action và Filter lấy cảm hứng từ WordPress (Blog_hooks) kết hợp chặt chẽ với cơ chế app_hooks() gốc của RISE CRM, giúp lập trình viên mở rộng quy trình xuất bản, giao diện frontend, siêu dữ liệu SEO và màn hình quản trị mà không cần sửa mã nguồn lõi. Tài liệu này tổng hợp đầy đủ các hàm API hook cốt lõi, vòng đời nội dung, bộ lọc SEO và toàn bộ hook tích hợp RISE CRM kèm ví dụ PHP chuẩn.
Hai loại Hook trong hệ thống
PolyCMS chia cơ chế mở rộng thành hai nhóm bổ trợ cho nhau:
- Actions (Hành động): Thực thi mã tùy biến tại các thời điểm xác định trong vòng đời ứng dụng (ví dụ: gửi webhook ngay khi bài viết chuyển sang xuất bản hoặc chèn thẻ theo dõi vào
<head>).
- Filters (Bộ lọc): Chặn, biến đổi và trả về dữ liệu trước khi PolyCMS lưu vào cơ sở dữ liệu hoặc kết xuất ra trình duyệt (ví dụ: bổ sung nội dung cuối bài viết, tùy biến thẻ SEO hoặc giới hạn quyền xem bài).
Các hàm API Hook cốt lõi của PolyCMS
Toàn bộ hàm hook của PolyCMS được định nghĩa trong plugins/polycms/Helpers/polycms_hooks_helper.php và điều phối qua lớp Libraries/Blog_hooks.php.
Đăng ký một Action
polycms_add_action(string $hook, callable $callback, int $priority = 10, int $args = 1);
$hook - Tên định danh của action hook.
$callback - Tên hàm, closure hoặc mảng [$object, 'method'] sẽ được gọi thực thi.
$priority - Độ ưu tiên thực thi (số càng nhỏ chạy càng sớm). Mặc định: 10.
$args - Số lượng tham số truyền vào hàm callback. Mặc định: 1.
// Ghi nhật ký hoặc gửi thông báo webhook ngay khi xuất bản bài viết mới
polycms_add_action('polycms_post_published', function ($post) {
$payload = [
'event' => 'post_published',
'id' => (int) $post->id,
'title' => (string) $post->title,
'url' => polycms_get_post_permalink($post),
];
polycms_log_activity('Da dua vao hang doi webhook cho bai viet: ' . $payload['title']);
}, 10, 1);
Đăng ký một Filter
polycms_add_filter(string $hook, callable $callback, int $priority = 10, int $args = 1);
Hàm callback của Filter bắt buộc phải trả về (return) giá trị sau khi xử lý để không làm đứt chuỗi dữ liệu của các bộ lọc phía sau.
// Tự động chèn ghi chú bản quyền vào cuối nội dung mỗi bài viết
polycms_add_filter('polycms_post_content', function ($content) {
return $content . '<p class="editorial-notice"><em>Nội dung thể hiện quan điểm của tác giả bài viết.</em></p>';
}, 20, 1);
Kích hoạt, gỡ bỏ và gỡ lỗi Hooks
// Kích hoạt một Action
polycms_do_action(string $hook, ...$args);
// Áp dụng Filter lên một giá trị
$value = polycms_apply_filters(string $hook, $value, ...$args);
// Gỡ bỏ callback đã đăng ký trước đó
polycms_remove_action(string $hook, callable $callback, int $priority = 10);
polycms_remove_filter(string $hook, callable $callback, int $priority = 10);
// Kiểm tra và bật chế độ ghi log debug hook khi phát triển
$has_action = polycms_has_action('polycms_head');
$has_filter = polycms_has_filter('polycms_post_content');
$fire_count = polycms_did_action('polycms_init');
$all_hooks = polycms_get_registered_hooks('all'); // 'action', 'filter', hoặc 'all'
$callbacks = polycms_get_hook_callbacks('polycms_post_content', 'filter');
polycms_debug_hooks(true); // Ghi log debug vào hệ thống nhật ký CodeIgniter
Danh mục đầy đủ các Hooks trong PolyCMS
Action vòng đời Bài viết (Post Lifecycle)
| Tên Hook |
Thời điểm kích hoạt |
Tham số truyền vào |
polycms_post_save |
Ngay trước khi bản ghi bài viết được lưu vào cơ sở dữ liệu |
$data (array) |
polycms_post_saved |
Ngay sau khi bài viết được tạo mới hoặc cập nhật |
$post (object) |
polycms_post_published |
Khi bài viết chuyển sang trạng thái published |
$post (object) |
polycms_post_delete |
Ngay trước khi xóa bài viết khỏi cơ sở dữ liệu |
$post_id (int) |
polycms_post_deleted |
Sau khi bài viết đã được xóa thành công |
$post_id (int) |
polycms_post_status_changed |
Khi trạng thái bài viết thay đổi |
$post, $old_status, $new_status |
Action vòng đời Trang tĩnh (Page Lifecycle)
| Tên Hook |
Thời điểm kích hoạt |
Tham số truyền vào |
polycms_page_saved |
Sau khi trang tĩnh được tạo mới hoặc cập nhật |
$page (object) |
polycms_page_deleted |
Sau khi trang tĩnh bị xóa khỏi hệ thống |
$page_id (int) |
Action Bình luận (Comments)
| Tên Hook |
Thời điểm kích hoạt |
Tham số truyền vào |
polycms_comment_submitted |
Khi độc giả gửi một bình luận mới |
$comment (object) |
polycms_comment_approved |
Khi quản trị viên duyệt hiển thị bình luận |
$comment (object) |
polycms_comment_deleted |
Khi bình luận bị xóa |
$comment_id (int) |
Action kết xuất Frontend và Giao diện Quản trị
| Tên Hook |
Thời điểm kích hoạt |
Tham số truyền vào |
polycms_init |
Ngay sau khi PolyCMS nạp xong toàn bộ sub-plugin đang kích hoạt |
Không có |
polycms_frontend_init |
Khi controller công khai Frontend khởi tạo |
Không có |
polycms_enqueue_scripts |
Khi theme hoặc plugin nạp CSS/JS ngoài frontend |
$context ('frontend') |
polycms_head |
Nằm bên trong thẻ <head> của giao diện frontend |
Không có |
polycms_wp_head |
Kích hoạt trong polycms_head() sau khi in các stylesheet đã đăng ký |
Không có |
polycms_head_meta_tags |
Bên trong <head> ngay sau các thẻ SEO, Open Graph và Twitter mặc định |
$entity (post, page, category, tag hoặc null) |
polycms_body_start |
Ngay sau thẻ mở <body> (phù hợp cho banner thông báo đầu trang) |
Không có |
polycms_footer |
Ngay trước thẻ đóng </body> của frontend |
Không có |
polycms_wp_footer |
Kích hoạt trong polycms_footer() sau khi in các script chân trang |
Không có |
polycms_footer_scripts |
Ở cuối tệp footer theme sau khi các script lõi đã tải xong |
Không có |
polycms_single_post_view |
Khi khách truy cập mở xem một bài viết chi tiết (dùng cho bộ đếm lượt xem) |
$post (object) |
polycms_before_render_post |
Trước khi kết xuất giao diện chi tiết bài viết |
$post (object) |
polycms_after_render_post |
Sau khi kết xuất giao diện chi tiết bài viết |
$post, $output |
polycms_after_render_homepage |
Sau khi kết xuất trang chủ blog |
$output |
polycms_admin_bar_actions |
Chèn nút thao tác tùy biến trên thanh admin bar ngoài frontend |
Không có |
polycms_dashboard_widgets |
Hiển thị widget thống kê tùy biến trong màn hình PolyCMS Dashboard |
Không có |
polycms_seo_box_before_fields |
Phía trên khối Core SEO trong màn hình sửa Bài viết/Trang (MTOptimize sử dụng) |
$entity, $type |
polycms_seo_box_content |
Bên trong khối Core SEO để mở rộng phân tích từ khóa và Schema (MTOptimize sử dụng) |
$entity, $type |
Bộ lọc Nội dung, Bố cục và Permalink
| Tên Filter |
Đối tượng áp dụng |
Tham số đầu vào |
Giá trị trả về kỳ vọng |
polycms_post_content |
Nội dung HTML bài viết trước khi hiển thị |
$content (string), $post |
Chuỗi HTML đã biến đổi |
polycms_post_title |
Tiêu đề bài viết trước khi hiển thị |
$title (string) |
Chuỗi tiêu đề mới |
polycms_post_excerpt |
Mô tả ngắn của bài viết |
$excerpt (string), $post |
Chuỗi mô tả đã chỉnh sửa |
polycms_page_content |
Nội dung HTML trang tĩnh trước khi hiển thị |
$content (string), $page |
Chuỗi HTML đã biến đổi |
polycms_the_content |
Đường ống lọc nội dung thống nhất (MTBuilder sử dụng) |
$content (string), $entity |
Chuỗi HTML đã biến đổi |
polycms_post_meta |
Mảng thông tin tác giả, ngày đăng, lượt xem, chuyên mục và thẻ tag |
$meta (array), $post |
Mảng siêu dữ liệu mới |
polycms_post_permalink |
Đường dẫn URL tĩnh của bài viết |
$permalink (string), $post |
Chuỗi URL mới |
polycms_page_permalink |
Đường dẫn URL cấp gốc của trang tĩnh |
$url (string), $page |
Chuỗi URL mới |
polycms_body_class |
Mảng các lớp CSS gán cho thẻ <body> |
$classes (array) |
Mảng lớp CSS mới |
polycms_branding_display |
Chế độ hiển thị thương hiệu (both, logo, brand, none) |
$mode (string) |
Chuỗi chế độ hiển thị |
Bộ lọc SEO và Cổng đăng nhập Khách hàng
| Tên Filter |
Đối tượng áp dụng |
Tham số đầu vào |
polycms_seo_meta_tags |
Mảng dữ liệu đầu vào của polycms_get_seo_meta_tags() |
$data (array) |
polycms_open_graph_tags |
Mảng dữ liệu đầu vào của polycms_get_open_graph_tags() |
$data (array) |
polycms_twitter_card_tags |
Mảng dữ liệu đầu vào của polycms_get_twitter_card_tags() |
$data (array) |
polycms_meta_title |
Giá trị thẻ <title> cuối cùng |
$title (string) |
polycms_meta_description |
Chuỗi mô tả meta cuối cùng |
$description (string) |
polycms_og_tags |
Mảng thẻ Open Graph |
$tags (array) |
polycms_twitter_tags |
Mảng thẻ Twitter Card |
$tags (array) |
polycms_frontend_customer_gate_enabled |
Bật hoặc tắt yêu cầu đăng nhập khách hàng RISE ngoài frontend |
$enabled (bool) |
polycms_frontend_customer_gate_authorized |
Kiểm tra phiên hiện tại có vượt qua cổng đăng nhập hay không |
$authorized (bool) |
polycms_frontend_customer_gate_login_url |
URL trang đăng nhập dùng khi chuyển hướng khách chưa xác thực |
$login_url (string) |
polycms_frontend_customer_gate_bypass |
Cho phép bỏ qua cổng đăng nhập cho các đường dẫn chỉ định |
$bypass (bool), $request_uri |
Action vòng đời Plugin và Theme
| Tên Hook |
Thời điểm kích hoạt |
Tham số truyền vào |
polycms_plugin_installed |
Sau khi tải lên tệp ZIP sub-plugin và ghi nhận vào database |
$plugin_file (string) |
polycms_plugin_activated |
Khi kích hoạt sub-plugin trong PolyCMS > Plugins |
$plugin_file (string) |
polycms_plugin_deactivated |
Khi tắt kích hoạt sub-plugin trong PolyCMS > Plugins |
$plugin_file (string) |
polycms_plugin_settings_save_{slug} |
Khi biểu mẫu cấu hình sub-plugin gửi POST (dấu - đổi thành _) |
$post_data (array) |
polycms_theme_loaded |
Ngay sau khi theme đang kích hoạt và tệp functions.php tải xong |
$theme (object) |
polycms_theme_switched |
Khi quản trị viên chuyển đổi sang theme khác |
$new_theme, $old_theme |
Các Hook tích hợp RISE CRM được PolyCMS sử dụng
Bên cạnh bộ máy Blog_hooks nội bộ, PolyCMS kết nối trực tiếp vào bộ điều phối CodeIgniter 4 gốc của RISE CRM thông qua app_hooks(). Nắm vững các điểm tích hợp này giúp bạn mở rộng thanh điều hướng, phân quyền và lớp bảo mật của RISE CRM một cách chuẩn xác.
| Hook của RISE CRM |
Loại |
Cách PolyCMS sử dụng |
app_filter_staff_left_menu |
Filter |
Đăng ký hai nhóm menu PolyCMS và Appearance, kích hoạt admin_init và nạp tự động các mục từ menu.json của sub-plugin đang bật |
app_filter_client_left_menu |
Filter |
Thêm mục Blog vào thanh menu bên trái của Cổng Khách hàng RISE khi bật tùy chọn polycms_show_in_client_menu |
app_hook_role_permissions_extension |
Action |
Hiển thị 5 quyền RBAC chi tiết (polycms_view, polycms_create, polycms_edit, polycms_delete, polycms_settings) trong Settings > Access Permission > Roles |
app_filter_role_permissions_save_data |
Filter |
Lưu lại các quyền PolyCMS đã tích chọn khi quản trị viên cập nhật vai trò nhân sự RISE |
app_filter_app_csrf_exclude_uris |
Filter |
Tự động miễn trừ mẫu cms/api/v1.*+ khỏi kiểm tra CSRF của RISE để REST API phi trạng thái xử lý POST, PUT, DELETE trơn tru |
app_hook_head_extension |
Action |
Nạp bộ CSS tương thích Bootstrap 5 (rise-bs5-compat.css), Select2 và CSS cho TinyMCE chỉ trên các route quản trị PolyCMS |
app_hook_layout_main_view_extension |
Action |
Nạp TinyMCE, SweetAlert2, Select2 trên màn hình quản trị PolyCMS và kích hoạt cầu nối app_admin_footer cho các sub-plugin như MTBuilder |
app_hook_before_app_access |
Action |
Kiểm tra tùy chọn chuyển hướng trang chủ polycms_enable_homepage_redirect (mặc định tắt trên RISE CRM để bảo vệ /dashboard và /signin) |
// Ví dụ: Chèn mục menu tùy biến vào nhóm PolyCMS bằng app_hooks() của RISE CRM
app_hooks()->add_filter('app_filter_staff_left_menu', function ($sidebar_menu) {
if (!polycms_is_admin() && !polycms_staff_can('view', 'polycms')) {
return $sidebar_menu;
}
if (isset($sidebar_menu['polycms']['submenu'])) {
$sidebar_menu['polycms']['submenu'][] = [
'name' => 'Lịch Biên Tập',
'url' => polycms_admin_url('polycms/plugins/settings/editorial-calendar'),
'is_custom_menu_item' => true,
];
}
return $sidebar_menu;
}, 20);
Các ví dụ lập trình PHP thực tế
Ví dụ 1: Tự động tạo trích dẫn bài viết sạch
polycms_add_filter('polycms_post_excerpt', function ($excerpt, $post = null) {
if (empty($excerpt) && is_object($post) && !empty($post->content)) {
$plain = trim(strip_tags($post->content));
return mb_substr($plain, 0, 160, 'UTF-8') . '...';
}
return $excerpt;
}, 10, 2);
Ví dụ 2: Nhúng Google Tag Manager vào phần đầu trang frontend
polycms_add_action('polycms_head', function () {
$gtm_id = trim((string) polycms_get_option('polycms_gtm_id', ''));
if ($gtm_id !== '' && !polycms_is_staff_logged_in()) {
$safe_id = html_escape($gtm_id);
echo "<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});"
. "var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;"
. "j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})"
. "(window,document,'script','dataLayer','{$safe_id}');</script>\n";
}
});
Ví dụ 3: Giới hạn bài viết riêng tư chỉ dành cho nhân viên RISE đã đăng nhập
polycms_add_filter('polycms_post_content', function ($content, $post = null) {
$CI = &polycms_ci();
if (!$post) {
$post = $CI->load->get_var('post');
}
if (is_object($post) && ($post->visibility ?? 'public') === 'private' && !polycms_is_staff_logged_in()) {
return '<div class="alert alert-warning">Nội dung này chỉ dành cho nhân sự nội bộ đã đăng nhập hệ thống.</div>';
}
return $content;
}, 10, 2);
Nguyên tắc phát triển tốt nhất
- Khai báo rõ độ ưu tiên (
priority): Mặc định là 10. Đặt số nhỏ hơn (như 5) để chạy trước các plugin đi kèm, hoặc lớn hơn (như 20) để xử lý sau cùng.
- Luôn trả về giá trị trong Filter: Thiếu lệnh
return sẽ làm trống chuỗi nội dung hoặc hỏng cấu trúc mảng dữ liệu.
- Ưu tiên dùng hàm
polycms_* chống xung đột: Luôn sử dụng polycms_ci(), polycms_get_option() và polycms_is_staff_logged_in() để đảm bảo an toàn khi chạy song song với nhiều plugin RISE CRM khác.
- Đặt tiền tố cho hàm hoặc dùng closure: Thêm tiền tố theo slug plugin (ví dụ
myplugin_) để tránh đụng tên hàm toàn cục.
- Giữ Filter thuần túy: Không ghi dữ liệu vào database trong các filter hiển thị; hãy sử dụng action vòng đời chuyên biệt cho thao tác ghi.
Tài liệu liên quan