Back to Main Site

Tài liệu tham khảo đầy đủ về Hooks và Filters trong PolyCMS cho RISE CRM

Last updated on Nov 22, 2026 7:38 AM 7:38 AM 2,631.14 ms

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ẻ &lt;head&gt; 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 &lt;head&gt; 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ở &lt;body&gt; (phù hợp cho banner thông báo đầu trang) Không có
polycms_footer Ngay trước thẻ đóng &lt;/body&gt; 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ẻ &lt;body&gt; $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ẻ &lt;title&gt; 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

  1. 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.
  2. 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.
  3. Ư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.
  4. Đặ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.
  5. 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