Hướng dẫn xây dựng Plugin tùy biến cho PolyCMS trên RISE CRM
PolyCMS cho RISE CRM sử dụng kiến trúc sub-plugin độc lập đặt tại plugins/polycms/plugins/{slug}/, cho phép bạn bổ sung tính năng biên tập, widget thống kê, shortcode, khối MTBuilder hoặc tích hợp hệ thống bên ngoài mà không chỉnh sửa mã nguồn lõi. Hướng dẫn này cung cấp khung mã mẫu hoàn chỉnh sử dụng tiêu đề PHP docblock chuẩn, tệp menu.json chèn menu thanh bên RISE CRM, trang cấu hình tập trung và các hàm helper chống xung đột.
Yêu cầu chuẩn bị
Bạn cần nắm cơ bản về PHP 8.1+, cấu trúc CodeIgniter 4 và cách hoạt động của Hệ thống Hooks và Filters trong PolyCMS.
Cấu trúc thư mục Plugin
Mọi sub-plugin đều đặt bên trong plugins/polycms/plugins/. PolyCMS tự động nhận diện bất kỳ thư mục nào chứa tệp khởi chạy {slug}.php (hoặc tệp .php ở thư mục gốc plugin) có phần chú thích tiêu đề Plugin Name:.
plugins/polycms/plugins/
\-- my-custom-plugin/
|-- my-custom-plugin.php # Tệp chính kèm PHP docblock header (bắt buộc)
|-- menu.json # Khai báo mục menu trên sidebar RISE CRM (tùy chọn)
|-- views/
| \-- settings.php # Giao diện trang cấu hình (tùy chọn)
|-- assets/
| |-- css/
| | \-- style.css # CSS của plugin
| \-- js/
| \-- script.js # JS của plugin
\-- languages/
\-- english.php # Tệp ngôn ngữ mở rộng (tùy chọn)
Mở rộng MTBuilder từ khung Plugin của bạn
Nếu muốn cung cấp các khối giao diện kéo thả phục vụ đội ngũ tiếp thị thay vì viết cứng HTML trong theme, hãy tổ chức mã mở rộng MTBuilder ngay trong cùng thư mục plugin:
my-custom-plugin/
|-- my-custom-plugin.php
|-- menu.json
|-- assets/
| |-- js/
| | |-- script.js
| | \-- mtbuilder-blocks.js # MTBuilder.registerBlock() + bộ lọc sidebar
| \-- css/
| \-- mtbuilder-blocks.css # CSS tùy chọn cho editor/frontend
|-- includes/
| \-- class-mtbuilder-extension.php
\-- views/
\-- settings.php
Bước 1: Tạo tệp chính kèm tiêu đề PHP Docblock
PolyCMS cho RISE CRM nhận diện thông tin plugin trực tiếp từ khối docblock PHP ở đầu tệp plugins/polycms/plugins/my-custom-plugin/my-custom-plugin.php. Luôn kiểm tra hằng BASEPATH ở đầu tệp và sử dụng bộ hàm polycms_* an toàn cho RISE CRM.
<?php
/**
* Plugin Name: My Custom Plugin
* Plugin URI: https://your-website.com/my-custom-plugin
* Description: Tự động thêm khung giới thiệu tác giả cuối bài và ghi nhật ký lưu bài trên RISE CRM.
* Version: 1.0.0
* Author: Tên Của Bạn
* Author URI: https://your-website.com
* Text Domain: my-custom-plugin
* Requires PolyCMS: 1.3.0
* Requires PHP: 8.1
*/
defined('BASEPATH') or exit('No direct script access allowed');
define('MCP_PLUGIN_VERSION', '1.0.0');
define('MCP_PLUGIN_SLUG', 'my-custom-plugin');
// =============================================
// HOOK KÍCH HOẠT VÀ TẮT KÍCH HOẠT
// =============================================
polycms_add_action('polycms_plugin_activated', function ($plugin_file) {
if ($plugin_file === 'my-custom-plugin/my-custom-plugin.php') {
if (polycms_get_plugin_option(MCP_PLUGIN_SLUG, 'show_author_bio') === null) {
polycms_update_plugin_option(MCP_PLUGIN_SLUG, 'show_author_bio', 'yes');
}
polycms_log_activity('My Custom Plugin da duoc kich hoat.');
}
}, 10, 1);
polycms_add_action('polycms_plugin_deactivated', function ($plugin_file) {
if ($plugin_file === 'my-custom-plugin/my-custom-plugin.php') {
polycms_clear_cache();
polycms_log_activity('My Custom Plugin da tat kich hoat.');
}
}, 10, 1);
// =============================================
// HOOK NỘI DUNG, FRONTEND VÀ VÒNG ĐỜI BÀI VIẾT
// =============================================
polycms_add_filter('polycms_post_content', 'mcp_append_author_box', 20, 2);
polycms_add_action('polycms_head', 'mcp_inject_styles');
polycms_add_action('polycms_post_saved', 'mcp_on_post_saved', 10, 1);
function mcp_append_author_box($content, $post = null)
{
$CI = &polycms_ci();
if (!$post) {
$post = $CI->load->get_var('post');
}
if (!is_object($post)) {
return $content;
}
$show_bio = polycms_get_plugin_option(MCP_PLUGIN_SLUG, 'show_author_bio', 'yes');
if ($show_bio !== 'yes') {
return $content;
}
$author_name = trim(($post->firstname ?? '') . ' ' . ($post->lastname ?? ''));
if ($author_name === '') {
$author_name = 'Ban Biên Tập';
}
$custom_note = (string) polycms_get_plugin_option(MCP_PLUGIN_SLUG, 'bio_note', '');
$note_html = $custom_note !== '' ? '<p>' . html_escape($custom_note) . '</p>' : '';
$bio_html = '<div class="mcp-author-box">'
. '<h4>Giới thiệu tác giả</h4>'
. '<p>Biên soạn bởi <strong>' . html_escape($author_name) . '</strong></p>'
. $note_html
. '</div>';
return $content . $bio_html;
}
function mcp_inject_styles()
{
$css_url = polycms_plugin_url(MCP_PLUGIN_SLUG, 'assets/css/style.css');
echo '<link rel="stylesheet" href="' . esc_attr($css_url) . '?v=' . MCP_PLUGIN_VERSION . '">' . "\n";
}
function mcp_on_post_saved($post)
{
if (is_object($post) && !empty($post->id)) {
polycms_log_activity('PolyCMS post saved: ' . ($post->title ?? '') . ' (ID: ' . (int) $post->id . ')');
}
}
// =============================================
// HOOK LƯU CẤU HÌNH TẬP TRUNG
// =============================================
// Tự động được Plugins::settings() kích hoạt khi gửi POST tới:
// /polycms/plugins/settings/my-custom-plugin
polycms_add_action('polycms_plugin_settings_save_my_custom_plugin', function ($post_data) {
$show_bio = (isset($post_data['show_author_bio']) && $post_data['show_author_bio'] === 'no') ? 'no' : 'yes';
$bio_note = trim(strip_tags((string) ($post_data['bio_note'] ?? '')));
polycms_update_plugin_option(MCP_PLUGIN_SLUG, 'show_author_bio', $show_bio);
polycms_update_plugin_option(MCP_PLUGIN_SLUG, 'bio_note', $bio_note);
polycms_clear_cache();
}, 10, 1);
Các trường khai báo hợp lệ trong PHP Docblock
| Trường khai báo | Bắt buộc | Mô tả |
|---|---|---|
Plugin Name: |
Có | Tên hiển thị trong màn hình PolyCMS > Plugins |
Description: |
Khuyến nghị | Mô tả ngắn trên danh sách plugin |
Version: |
Khuyến nghị | Phiên bản ngữ nghĩa (mặc định 1.0.0) |
Author: |
Tùy chọn | Tên tác giả hoặc đơn vị phát triển |
Plugin URI: |
Tùy chọn | Liên kết trang tài liệu hoặc trang sản phẩm |
Author URI: |
Tùy chọn | Liên kết website tác giả |
Text Domain: |
Tùy chọn | Định danh miền ngôn ngữ |
Requires PolyCMS: |
Tùy chọn | Phiên bản PolyCMS tối thiểu |
Requires PHP: |
Tùy chọn | Phiên bản PHP tối thiểu (ví dụ 8.1) |
Bước 2: Chèn mục Menu vào thanh bên RISE CRM bằng menu.json
Khi plugin đang ở trạng thái kích hoạt, bộ lọc app_filter_staff_left_menu của PolyCMS tự động đọc tệp plugins/polycms/plugins/{slug}/menu.json và gắn mục điều hướng vào thanh bên nhân viên RISE CRM dưới nhóm PolyCMS ("parent": "polycms") hoặc Appearance ("parent": "polycms-appearance").
plugins/polycms/plugins/my-custom-plugin/menu.json
[
{
"slug": "polycms-my-custom-plugin",
"name": "My Custom Plugin",
"href": "polycms/plugins/settings/my-custom-plugin",
"parent": "polycms",
"position": 28
}
]
Đường dẫn href được PolyCMS tự động chuẩn hóa qua polycms_admin_url().
Bước 3: Tạo giao diện trang cấu hình (views/settings.php)
Chỉ cần có tệp views/settings.php trong thư mục plugin, màn hình PolyCMS > Plugins sẽ tự động hiển thị nút Settings. Khi quản trị viên bấm lưu, Controllers/Plugins.php kiểm tra quyền RBAC, gọi hook polycms_plugin_settings_save_my_custom_plugin, tạo thông báo flash qua polycms_set_alert() và chuyển hướng bằng polycms_redirect().
plugins/polycms/plugins/my-custom-plugin/views/settings.php
<?php
defined('BASEPATH') or exit('No direct script access allowed');
$show_author_bio = polycms_get_plugin_option('my-custom-plugin', 'show_author_bio', 'yes');
$bio_note = (string) polycms_get_plugin_option('my-custom-plugin', 'bio_note', '');
?>
<div class="card">
<div class="card-header">
<h4 class="mb-0">Cấu hình My Custom Plugin</h4>
</div>
<div class="card-body">
<form method="post" action="<?php echo esc_attr(polycms_admin_url('polycms/plugins/settings/my-custom-plugin')); ?>">
<?php echo polycms_csrf_field(); ?>
<div class="mb-3">
<label for="show_author_bio" class="form-label">Hiển thị khung giới thiệu tác giả</label>
<select name="show_author_bio" id="show_author_bio" class="form-select">
<option value="yes" <?php echo $show_author_bio === 'yes' ? 'selected' : ''; ?>>Có</option>
<option value="no" <?php echo $show_author_bio === 'no' ? 'selected' : ''; ?>>Không</option>
</select>
</div>
<div class="mb-3">
<label for="bio_note" class="form-label">Ghi chú biên tập mặc định</label>
<textarea name="bio_note" id="bio_note" class="form-control" rows="4"><?php echo html_escape($bio_note); ?></textarea>
<div class="form-text">Đoạn văn bản thuần tùy chọn hiển thị dưới tên tác giả.</div>
</div>
<button type="submit" class="btn btn-primary">Lưu cấu hình</button>
</form>
</div>
</div>
Bước 4: Thêm tài nguyên CSS và Hook mở rộng MTBuilder
plugins/polycms/plugins/my-custom-plugin/assets/css/style.css
.mcp-author-box {
margin-top: 2rem;
padding: 1.5rem;
background: #f8fafc;
border-left: 4px solid #3b82f6;
border-radius: 8px;
}
.mcp-author-box h4 {
margin: 0 0 0.5rem 0;
color: #0f172a;
font-size: 1rem;
}
Nếu plugin đăng ký thêm khối MTBuilder, hãy chỉ nạp script trên đường dẫn trình dựng trang thông qua hook app_admin_footer (được PolyCMS bắc cầu từ app_hook_layout_main_view_extension của RISE CRM):
app_hooks()->add_action('app_admin_footer', function () {
$CI = &polycms_ci();
$uri = $CI->uri->uri_string();
if (strpos($uri, 'polycms/mtbuilder/editor') !== false) {
$src = polycms_asset_url('plugins/my-custom-plugin/assets/js/mtbuilder-blocks.js');
echo '<script src="' . esc_attr($src) . '?v=' . MCP_PLUGIN_VERSION . '"></script>' . "\n";
}
});
Bước 5: Thêm tệp hỗ trợ ngôn ngữ
PolyCMS tự động nạp các tệp dịch .php nằm trong thư mục plugins/polycms/plugins/my-custom-plugin/languages/ khi tải plugin.
plugins/polycms/plugins/my-custom-plugin/languages/english.php
<?php
defined('BASEPATH') or exit('No direct script access allowed');
$lang['mcp_plugin_name'] = 'My Custom Plugin';
$lang['mcp_show_author_bio'] = 'Show Author Bio Box';
$lang['mcp_settings_saved'] = 'Settings saved successfully.';
Các hàm Helper hỗ trợ phát triển Plugin
| Hàm | Chức năng |
|---|---|
polycms_get_plugin_option($slug, $key, $default = null) |
Đọc tùy chọn plugin từ bảng {prefix}blog_plugin_options |
polycms_update_plugin_option($slug, $key, $value) |
Lưu hoặc cập nhật tùy chọn plugin |
polycms_delete_plugin_option($slug, $key) |
Xóa một tùy chọn cụ thể của plugin |
polycms_get_plugin_options($slug) |
Lấy toàn bộ tùy chọn của plugin dưới dạng mảng khóa-giá trị |
polycms_delete_plugin_options($slug) |
Xóa toàn bộ tùy chọn của plugin khi gỡ cài đặt |
polycms_get_plugin_settings_url($slug) |
Lấy URL trang cấu hình plugin trong quản trị RISE CRM |
polycms_plugin_url($slug, $path = '') |
Lấy URL công khai tới thư mục plugins/polycms/plugins/{slug}/ |
polycms_plugin_path($slug, $path = '') |
Lấy đường dẫn vật lý trên máy chủ tới thư mục plugin |
polycms_is_plugin_active($slug) |
Kiểm tra một sub-plugin có đang bật hay không |
polycms_register_widget($widget_class) |
Đăng ký lớp widget mới kế thừa từ Blog_widget |
Cài đặt và Kiểm duyệt Bảo mật
- Tải thư mục
my-custom-plugin/vào{rise_crm_root}/plugins/polycms/plugins/(hoặc nén thành tệp.zipvà tải lên qua PolyCMS > Plugins > Upload Plugin). - Truy cập PolyCMS > Plugins trong RISE CRM.
- Tìm My Custom Plugin và bấm Activate.
- Mở nút Settings hoặc mục tương ứng trên thanh bên để cấu hình.
Lưu ý rằng Blog_plugin_loader::validate_plugin() kiểm duyệt đường dẫn bằng polycms_validate_file_path(), giới hạn kích thước tệp chính tối đa 5 MB và chặn các plugin chứa hàm nguy hiểm (eval, exec, shell_exec, system, passthru, proc_open, popen). Tệp ZIP tải lên cũng đi qua polycms_safe_extract_zip() để chống Zip Slip, symlink độc hại và Zip Bomb.
Nguyên tắc phát triển tốt nhất
- Đặt tiền tố cho mọi hàm và hằng số: Dùng tiền tố ngắn như
mcp_để tránh trùng lặp với các plugin khác. - Dùng bộ hàm
polycms_*chuẩn RISE CRM: Luôn gọipolycms_ci(),polycms_admin_url(),polycms_set_alert(),polycms_redirect()vàpolycms_log_activity(). - Chèn
polycms_csrf_field()vào mọi biểu mẫu POST: Đảm bảo mọi biểu mẫu quản trị tương thích với bảo vệ CSRF gốc của RISE CRM. - Dùng API Plugin Options: Lưu các cấu hình đơn giản bằng
polycms_update_plugin_option()thay vì tự tạo bảng cơ sở dữ liệu riêng. - Giới hạn phạm vi tải tài nguyên: Chỉ xuất CSS/JS trên các đường dẫn cần thiết và gọi
polycms_clear_cache()khi thay đổi cài đặt ảnh hưởng giao diện công khai.
Hỗ trợ kỹ thuật
Nếu bạn cần hỗ trợ phát triển plugin tùy biến hoặc kết nối luồng nghiệp vụ RISE CRM với các hook PolyCMS, hãy để lại bình luận tại trang danh mục sản phẩm PolyXGO trên CodeCanyon để nhận hỗ trợ miễn phí.
Tài liệu liên quan
- Tạo Custom Blocks cho MTBuilder - Đăng ký khối kéo thả và nhóm sidebar tùy biến trong MTBuilder.
- Tài liệu tham khảo đầy đủ về Hooks và Filters - Tra cứu toàn bộ hook PolyCMS và RISE CRM.
- Tạo Shortcode tùy biến trong PolyCMS - Đăng ký mã ngắn động từ plugin.
- Xây dựng Theme tùy biến cho PolyCMS - Xây dựng giao diện phối hợp mượt mà với plugin và MTBuilder.
- Tổng quan kiến trúc PolyCMS - Xem bố cục thư mục, 19 bảng cơ sở dữ liệu và luồng định tuyến.