Hướng dẫn phát triển plugin WordPress: Xây dựng plugin đầu tiên từ con số 0

Công tác chuẩn bị và thiết lập môi trường

Trước khi bắt đầu viết mã, bạn cần đảm bảo rằng môi trường phát triển của mình đã được cấu hình đúng cách. Một môi trường phát triển địa phương tốt có thể nâng cao đáng kể hiệu suất phát triển và trải nghiệm gỡ lỗi.

Trước tiên, bạn cần cài đặt một môi trường máy chủ web trên máy tính cá nhân của mình; môi trường này thường được gọi là “môi trường máy chủ cục bộ”. Một trong những lựa chọn phổ biến nhất là XAMPP hoặc MAMP, vốn tích hợp sẵn các công cụ Apache, MySQL/MariaDB và PHP. Một giải pháp mạnh mẽ khác là sử dụng Docker để thiết lập một môi trường gần giống với môi trường sản xuất thực tế. Dù bạn chọn phương án nào, hãy đảm bảo rằng phiên bản PHP (khuyến nghị là 7.4 hoặc cao hơn) và phiên bản MySQL của bạn tương thích với hầu hết các môi trường lưu trữ WordPress.

Tiếp theo, hãy tải về và cài đặt phiên bản mới nhất của WordPress. Giải nén tệp WordPress vào thư mục gốc của trang web trên máy chủ của bạn (ví dụ: thư mục gốc của XAMPP). htdocs Hãy tạo một thư mục mới (ví dụ: “WordPress”) và thực hiện các bước cài đặt theo quy trình nổi tiếng “Cài đặt trong 5 phút”. Đảm bảo rằng bạn có thể truy cập trang web WordPress cục bộ này một cách bình thường.

Đọc thêm Dễ hiểu và sâu sắc: Hướng dẫn toàn diện từ đầu để thành thạo phát triển plugin WordPress。

Cuối cùng, và cũng là bước vô cùng quan trọng: Hãy chuẩn bị một trình soạn thảo mã nguồn. Chúng tôi khuyên bạn nên sử dụng các công cụ như Visual Studio Code, PhpStorm hoặc Sublime Text – những trình soạn thảo có chức năng làm nổi bật mã nguồn, gợi ý thông minh và hỗ trợ gỡ lỗi. Đặc biệt đối với việc phát triển bằng PHP, những tính năng này sẽ giúp bạn tránh được nhiều lỗi ngữ pháp cơ bản.

UltaHost – Nhà cung cấp dịch vụ máy chủ WordPress chuyên nghiệp

Bảo đảm hoàn tiền trong 30 ngày, băng thông và cơ sở dữ liệu không giới hạn, bảo vệ DDoS miễn phí, mua 3 năm ưu đãi 50%

Truy cập trang

Cấu trúc cơ bản của plugin và tệp chính (Plugin Basic Structure and Main File)

Một plugin WordPress có cấu trúc tệp tin tiêu chuẩn và bắt buộc; phần cốt lõi của nó nằm tại… /wp-content/plugins/ Thư mục có cùng tên trong danh mục, cùng với tệp PHP chính nằm bên trong thư mục đó.

Tạo tệp chính cho plugin

Đầu tiên, trong /wp-content/plugins/ Hãy tạo một thư mục mới trong thư mục đó. Tên thư mục nên ngắn gọn, duy nhất và phản ánh chức năng của plugin, ví dụ như “my-first-plugin”. Sau đó, hãy tạo một tệp PHP có cùng tên với thư mục đó bên trong nó. my-first-plugin.php。

Tệp chính này là “điểm vào” (entry point) của plugin; WordPress sẽ nhận diện thông tin metadata của plugin bằng cách đọc phần thông tin tiêu đề plugin (plugin header) ở đầu tệp. Thông tin tiêu đề plugin là một khối chú thích PHP tiêu chuẩn và phải được đặt ở đầu tệp. Điều kiện tối thiểu là tệp phải chứa tên plugin và mô tả của nó.

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个学习WordPress插件开发的示例插件，用于展示“Hello World”。
 * Version:           1.0.0
 * Author:            你的名字
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 * Domain Path:       /languages
 */

Trong đoạn mã trên,Plugin Name Những trường được đánh dấu là “bắt buộc” phải điền; các trường còn lại đều là tùy chọn nhưng được khuyến nghị nên điền. Thông tin này sẽ được hiển thị trên trang quản lý “Plugin” trong giao diện quản trị WordPress.Text Domain Được sử dụng cho mục đích quốc tế hóa (hỗ trợ nhiều ngôn ngữ), và phải phù hợp với các vùng chứa văn bản được sử dụng trong các lệnh gọi hàm dịch tiếp theo.

Đọc thêm Làm chủ phát triển plugin WordPress từ con số 0: Nguyên lý, thực hành và kỹ thuật nâng cao。

Định nghĩa các hằng số cơ bản của plugin

Những thói quen phát triển plugin tốt thường bắt đầu bằng việc định nghĩa một số hằng số hữu ích, chẳng hạn như đường dẫn tệp tin của plugin và địa chỉ URL, nhằm giúp việc trích dẫn chúng trở nên dễ dàng hơn trong các đoạn mã sau này. Điều này giúp tránh tình trạng phải ghi các đường dẫn trực tiếp (hardcoding), từ đó làm cho mã nguồ

Bạn có thể thêm đoạn mã sau vào tệp chính, ngay sau phần thông tin tiêu đề của plugin, để định nghĩa các hằng số:

// 防止直接访问
if ( ! defined( 'ABSPATH' ) ) {
    exit; // 如果 ABSPATH 未定义，则退出
}

// 定义插件路径和URL常量
define( 'MFP_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
define( 'MFP_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
define( 'MFP_PLUGIN_VERSION', '1.0.0' );

Ở đây,plugin_dir_path( FILE ) 和 plugin_dir_url( FILE ) Đây là một hàm cốt lõi do WordPress cung cấp, cho phép bạn lấy đường dẫn thư mục và URL của tệp plugin hiện tại một cách an toàn.MFP_PLUGIN_VERSION Các hằng số được sử dụng để lưu trữ số phiên bản của plugin, giúp việc thêm các định dạng script hoặc so sánh các phiên bản trở nên dễ dàng hơn.

Hosting.com - lưu trữ chia sẻ

Hiệu năng cao, được trang bị CPU AMD EPYC, lưu trữ SSD NVMe và LiteSpeed, hỗ trợ chuyên gia nội bộ 24 giờ/ngày, các biện pháp bảo mật tiên tiến bao gồm SSL, chống brute force, phần mềm độc hại và bảo vệ DDoS, tiết kiệm tới 73%.

Truy cập trang

Thực hiện chức năng cốt lõi và sử dụng hook

Bí quyết của việc phát triển plugin cho WordPress nằm ở việc sử dụng hệ thống “Hook” (Câu nối). Có hai loại Hook: Actions (Hành động) và Filters (Bộ lọc). Chúng cho phép bạn chèn mã của mình vào những thời điểm cụ thể trong quá trình hoạt động của WordPress (chẳng hạn như khi trang được tải, khi bài viết được lưu), hoặc thay đổi dữ liệu được trả về bởi các hàm khác.

Thêm một hook hành động đơn giản.

Hãy cùng thực hiện một tính năng đơn giản nhất: thêm một dòng văn bản vào phần chân trang (footer) của trang web. Chúng ta sẽ sử dụng các “action hook” (các hook hành động) để thực hiện điều này. wp_footerNó sẽ được kích hoạt trước khi HTML được hiển thị ở phần chân trang (footer).

Trong tệp chính, hãy thêm một hàm, sau đó sử dụng nó thông qua các lệnh hoặc đoạn mã khác trong tệp đó. add_action Hàm đó sẽ gắn (mount) nó lên… wp_footer hook này.

Đọc thêm Hướng dẫn phát triển plugin WordPress: Từng bước hướng dẫn bạn tạo plugin của riêng mình từ con số không。

/**
 * 在网站页脚输出自定义文本
 */
function mfp_display_footer_text() {
    echo '<p style="text-align: center; color: #666;">Cảm ơn bạn đã sử dụng plugin WordPress đầu tiên của tôi!</p>';
}
add_action( 'wp_footer', 'mfp_display_footer_text' );

Bây giờ, hãy kích hoạt plugin của bạn và truy cập giao diện người dùng (frontend) của trang web. Cuộn xuống phía dưới trang, bạn sẽ thấy dòng chữ này. Đây chính là cách sử dụng cơ bản của các “action hook”: thực hiện một hành động nhất định vào một thời điểm nhất định.

Sử dụng bộ lọc để chỉnh sửa nội dung.

Các bộ lọc (filters) được sử dụng để thay đổi giá trị hiện có của dữ liệu. Ví dụ, giả sử chúng ta muốn thay đổi tiêu đề của các bài viết bằng cách thêm từ “【Được đề xuất】” trước mỗi tiêu đề. Điều này có thể được thực hiện bằng cách sử dụng các bộ lọc phù hợp trong the_title Được thực hiện bằng cách sử dụng các bộ lọc (filters).

Máy chủ chia sẻ của InterServer

Lưu trữ chia sẻ với mức phí $2,50 USD mỗi tháng, giảm giá $0,1 USD trong tháng đầu tiên, mã giảm giá tryinterserver, với 461 ứng dụng đám mây và cài đặt chỉ bằng một cú nhấp chuột.

Truy cập trang

Hãy tạo một hàm mới, hàm này nhận vào làm tham số tiêu đề gốc cần được lọc, và trả về tiêu đề đã được sửa đổi. Sau đó, hãy sử dụng hàm đó để thực hiện công việc lọc. add_filter Mount.

/**
 * 在所有文章标题前添加前缀
 * @param string $title 原始标题
 * @return string 修改后的标题
 */
function mfp_add_prefix_to_title( $title ) {
    // 确保只在主循环中修改，避免影响后台列表等其他地方
    if ( is_single() && in_the_loop() ) {
        $title = '【推荐】' . $title;
    }
    return $title;
}
add_filter( 'the_title', 'mfp_add_prefix_to_title' );

Ví dụ đơn giản này cho thấy sức mạnh của bộ lọc: bạn có thể kiểm tra các điều kiện (chẳng hạn như…) is_single() Xác định xem đó có phải là trang của một bài viết đơn lẻ hay không; chỉ thực hiện các thay đổi trên nội dung trong bối cảnh cụ thể đó.

Thêm trang quản trị và các biện pháp bảo mật.

Một plugin có chức năng đầy đủ thường cần một trang cấu hình nền để quản trị viên trang web có thể thực hiện các thiết lập cần thiết. Đồng thời, việc đảm bảo an ninh cho mã nguồn là điều vô cùng quan trọng.

Trang cấu hình để tạo plugin

Chúng ta sẽ sử dụng add_menu_page Hàm này thêm một menu quản lý cấp cao và trang cài đặt tương ứng cho plugin.

Trước tiên, hãy tạo một hàm để tạo nội dung HTML cho trang cấu hình, sau đó gắn (mount) nó vào một đối tượng phù hợp trong ứng dụng. admin_menu Hãy sử dụng hàm của hook hành động để đăng ký menu này.

/**
 * 渲染插件设置页面的HTML内容
 */
function mfp_render_settings_page() {
    // 检查用户权限
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( __( '你没有足够的权限访问此页面。', 'my-first-plugin' ) );
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <p>Đây là trang cấu hình cho plugin đầu tiên của tôi. Trong tương lai, chúng tôi có thể thêm các biểu mẫu và tùy chọn vào đây.</p>
        <form action="/vi/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 后续可以在这里添加设置字段
            // settings_fields( 'mfp_options_group' );
            // do_settings_sections( 'mfp-settings-page' );
            // submit_button( '保存设置' );
            ?>
        <input type="hidden" name="trp-form-language" value="vi"/></form>
    </div>
    &lt;?php
}

/**
 * 注册插件管理菜单
 */
function mfp_add_admin_menu() {
    add_menu_page(
        &#039;我的第一个插件设置&#039;, // 页面标题
        &#039;我的插件&#039;,          // 菜单标题
        &#039;manage_options&#039;,    // 所需权限 (manage_options)
        &#039;mfp-settings-page&#039;, // 菜单slug
        &#039;mfp_render_settings_page&#039;, // 回调函数
        &#039;dashicons-admin-plugins&#039;, // 图标 (Dashicons)
        80                   // 菜单位置
    );
}
add_action( &#039;admin_menu&#039;, &#039;mfp_add_admin_menu&#039; );

Sau khi kích hoạt plugin, bạn sẽ thấy một mục menu mới có tên “My Plugins” ở bên trái giao diện quản trị WordPress. Nhấp vào mục này sẽ mở ra trang cấu hình đơn giản. Trang này được thiết kế để hỗ trợ việc thêm các trường biểu mẫu bằng cách sử dụng WordPress Settings API – đây là phương thức tiêu chuẩn để xử lý dữ liệu đầu vào từ người dùng một cách an toàn.

Xác thực và thoát dữ liệu

Mọi dữ liệu nhận được từ người dùng hoặc được truyền ra trình duyệt đều phải được xử lý nhằm ngăn chặn các cuộc tấn công từ chối dịch vụ (Cross-Site Scripting – XSS) và lỗ hổng SQL injection. WordPress cung cấp nhiều hàm bảo mật hữu ích để thực hiện điều này.

• Xuất dữ liệu an toàn: Sử dụng esc_html()、esc_attr()、esc_url() 和 wp_kses_post() Sử dụng các hàm như vậy để làm sạch nội dung được hiển thị trong HTML.
• Xác thực dữ liệu: Sử dụng sanitize_text_field()、sanitize_email() Sử dụng các hàm như vậy để làm sạch dữ liệu đầu vào được gửi từ biểu mẫu.
• Khóa không phải CE (Non-CE key): Đối với các thao tác trên biểu mẫu liên quan đến việc sửa đổi dữ liệu, bạn phải sử dụng khóa này. wp_nonce_field() 和 wp_verify_nonce() Để xác minh tính hợp lệ của yêu cầu.

An ninh là yếu tố then chốt trong quá trình phát triển các tiện ích mở rộng (plugin); vì vậy, chúng ta cần hình thành những thói quen tốt ngay từ đầu.

Tóm lại

Thông qua hướng dẫn này, chúng ta đã hoàn thành một quy trình phát triển plugin WordPress hoàn chỉnh – mặc dù plugin đó có thể nhỏ nhưng vẫn bao gồm đầy đủ các thành phần cần thiết. Chúng ta bắt đầu từ con số không, thiết lập môi trường phát triển, tạo cấu trúc tệp chính của plugin theo các tiêu chuẩn, và thông qua việc triển khai hai chức năng là thêm văn bản vào phần chân trang (footer) và chỉnh sửa tiêu đề bài viết, chúng ta đã hiểu sâu hơn về cách sử dụng các hook (điểm kết nối trong mã nguồn) cốt lõi của WordPress, đặc biệt là hook hành động (action hooks) và hook lọc (filter hooks). Cuối cùng, chúng ta cũng đã thêm một trang quản lý nền tảng cho plugin, đồng thời nhấn mạnh tầm quan trọng của các thực tiễn bảo mật như kiểm tra dữ liệu, kiểm soát quyền truy cập, và việc xử lý ký tự đặc biệt (output encoding).

Plugin đơn giản này, thuộc cấp độ “Hello World”, đã bao gồm tất cả các yếu tố cốt lõi cần thiết cho một plugin thương mại: cấu trúc chuẩn, khả năng sử dụng các hook (các hàm được gọi tự động trong quá trình thực thi plugin), giao diện quản trị nền (backend interface), và các biện pháp bảo mật. Từ điểm xuất phát này, bạn có thể thử tích hợp API Settings của WordPress để tạo ra các tùy chọn (options) thực sự, viết các bảng dữ liệu (database tables) tùy chỉnh, hoặc phát triển những đoạn mã ngắn (shortcodes) và công cụ hỗ trợ (tools) phức tạp hơn. Hãy nhớ rằng, việc liên tục học hỏi từ các hướng dẫn phát triển chính thức của WordPress và xem mã nguồn của các plugin mở nguồn (open-source) chất lượng cao là con đường tốt nhất để nâng cao kỹ năng của bạn.

FAQ 常见问题

Làm thế nào để gỡ lỗi (debug) plugin WordPress của tôi?
Bước đầu tiên là bật chế độ gỡ lỗi (debug mode) của WordPress. Trong quá trình thiết lập hoặc sửa đổi trang web của bạn… wp-config.php tệp, đặt giá trị của hằng số WP_DEBUG thành trueBạn cũng có thể thực hiện các thiết lập khác nữa. WP_DEBUG_LOG vì trueGhi thông tin lỗi vào… /wp-content/debug.log Trong tệp tin, cần tránh việc thông báo lỗi được hiển thị trực tiếp trên trang web vì điều này có thể ảnh hưởng đến người dùng.

Ngoài ra, việc sử dụng các công cụ trong gói công cụ phát triển trình duyệt (F12) như Console và Network để kiểm tra lỗi JavaScript và các yêu cầu API, cũng như tích hợp các công cụ gỡ lỗi PHP như Xdebug với trình soạn thảo mã của bạn (chẳng hạn VS Code) để thực hiện gỡ lỗi bằng cách đặt điểm dừng (breakpoints), đều là những phương pháp rất hiệu quả và chuyên nghiệp.

Tại sao plugin của tôi báo lỗi “lỗi nghiêm trọng” khi được kích hoạt?

Điều này thường xảy ra do lỗi ngữ pháp PHP hoặc do việc gọi một hàm/lớp không tồn tại. Trước tiên, hãy kiểm tra nhật ký lỗi của WordPress (như đã đề cập ở trên). Thông báo lỗi sẽ chỉ rõ ràng cho bạn biết dòng nào trong tập tin nào gặp vấn đề.

Các nguyên nhân phổ biến bao gồm: thiếu dấu chấm phẩy (;), khóa hoặc dấu ngoặc không khớp; việc gọi một hàm mà không có các tệp cần thiết; hoặc có đoạn mã vẫn cố gắng chạy sau khi plugin đã bị vô hiệu hóa. Hãy đảm bảo rằng phiên bản PHP của bạn phù hợp với yêu cầu, và tất cả các hàm đều được định nghĩa trước khi được sử dụng.

Làm thế nào để plugin của tôi hỗ trợ nhiều ngôn ngữ (hóa đa ngôn ngữ)?

WordPress sử dụng framework GNU gettext để thực hiện các chức năng quốc tế hóa (i18n) và địa phương hóa (l10n). Đầu tiên, như hướng dẫn đã chỉ ra, bạn cần thiết lập đúng các thông tin trong phần tiêu đề của tệp chính (main file header). Text Domain（ví dụ my-first-plugin）và Domain Path。

Trong mã nguồn của plugin, đối với tất cả các chuỗi cần được dịch, hãy sử dụng hàm dịch để bao bọc chúng. Ví dụ:__( ‘文本’, ‘my-first-plugin’ ) 或 _e( ‘文本’, ‘my-first-plugin’ )Sau đó, sử dụng các công cụ như Poedit để quét những chuỗi ký tự này trong mã nguồn, tạo ra tệp mẫu có định dạng .pot, và từ đó tạo ra các tệp .po và .mo dành cho ngôn ngữ tương ứng (ví dụ: tiếng Trung zh_CN), rồi đặt chúng vào đúng vị trí cần thiết. /languages/ thư mục chính xác.

Trong quá trình phát triển plugin, làm thế nào để tương tác với cơ sở dữ liệu một cách an toàn?

Đừng bao giờ viết trực tiếp các câu lệnh SQL để kết hợp dữ liệu đầu vào từ người dùng. Bạn phải sử dụng các lớp thao tác cơ sở dữ liệu được cung cấp bởi WordPress. $wpdbNó cung cấp những tính năng như… $wpdb->prepare() Phương pháp này cho phép xử lý các câu truy vấn SQL một cách an toàn bằng cách sử dụng các câu lệnh chuẩn bị (prepared statements), giúp ngăn chặn hiệu quả tình trạng xâm nhập dữ liệu (SQL injection).

Ví dụ, khi truy vấn dữ liệu, bạn nên viết như sau:

global $wpdb;
$user_input = $_POST['some_input'];
$safe_query = $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE column = %s", $user_input );
$results = $wpdb->get_results( $safe_query );

Đồng thời, cần thực hiện việc kiểm tra dữ liệu và làm sạch dữ liệu đầu vào của người dùng một cách nghiêm ngặt, chẳng hạn bằng cách sử dụng các công cụ hoặc quy trình phù hợp. sanitize_text_field() các hàm, v.v.