WordPress插件嘅基本結構同創建
開發一個WordPress插件由一個簡單嘅PHP檔案開始。呢個主要檔案必須包含特定嘅檔案頭註解，等WordPress可以識別同管理佢做插件。最基本嘅插件可以只係得一個檔案，例如 my-first-plugin.php。
<?php
/**
* Plugin Name: 我的第一个插件
* Plugin URI: https://example.com/my-first-plugin
* Description: 这是一个用于演示的简单WordPress插件。
* Version: 1.0.0
* Author: 开发者姓名
* License: GPL v2 or later
* Text Domain: my-first-plugin
*/檔案頭註解入面嘅「Plugin Name」係必需嘅，其他資料可以揀填。插件啟動之後，佢嘅功能係透過喺適當嘅時候執行PHP函數嚟實現。最常見嘅方法之一係用「動作掛鈎」。例如，想喺網頁嘅頁尾加一段文字，可以用 wp_footer 鉤子。
// 在页脚输出自定义内容
function myplugin_add_footer_text() {
echo '<p style="text-align:center;">多謝你使用我嘅插件！</p>';
}
add_action( 'wp_footer', 'myplugin_add_footer_text' );add_action 係WordPress核心函數，用嚟將自訂函數掛載到指定嘅動作掛鈎上面。插件目錄通常建議放喺 /wp-content/plugins/your-plugin-name/ 入面，除咗主要檔案，仲可以包含CSS、JavaScript、圖片等資源檔案。
推薦閱讀 WordPress主題終極指南：由揀選、自訂到開發嘅完整方案。
點樣為插件加管理菜單
為咗令插件喺WordPress後台有設定頁面，你需要幫佢加管理菜單。通常係透過 admin_menu 動作掛鉤嚟實現。
核心函數 add_menu_page 用嚟喺後台側邊欄加一個頂級菜單項目同埋對應嘅設定頁面。
function myplugin_add_admin_menu() {
add_menu_page(
'我的插件设置', // 页面标题
'我的插件', // 菜单标题
'manage_options', // 所需权限
'myplugin-settings', // 菜单slug
'myplugin_settings_page', // 显示页面的回调函数
'dashicons-admin-generic', // 图标（可选）
6 // 菜单位置（可选）
);
}
add_action( 'admin_menu', 'myplugin_add_admin_menu' );
// 设置页面的HTML内容
function myplugin_settings_page() {
?>
<div class="wrap">
<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
<form action="/yue/options.php/" method="post" data-trp-original-action="options.php">
<?php
settings_fields( 'myplugin_options' ); // 输出安全字段
do_settings_sections( 'myplugin-settings' ); // 输出设置区域
submit_button(); // 输出提交按钮
?>
<input type="hidden" name="trp-form-language" value="yue"/></form>
</div>
<?php
}建立咗個選單之後，下一步就係用WordPress嘅設定API去定義具體嘅可配置選項。
利用設定API保存插件配置設定
手動處理表單提交同安全性驗證係好麻煩又易出錯嘅。WordPress嘅設定API提供咗一套標準化方法嚟註冊、顯示同保存設定。主要涉及三個函數：register_setting, add_settings_section 同埋 add_settings_field。
以下示例示範點樣註冊一個選項組，同埋加一個文字欄位。
推薦閱讀 WordPress網站性能優化指南：深入分析與實踐策略。
function myplugin_settings_init() {
// 注册一个新的设置项到数据库 `wp_options` 表中
register_setting( 'myplugin_options', 'myplugin_settings' );
// 在设置页面添加一个新的区域
add_settings_section(
'myplugin_section_basic', // 区域ID
'基础设置', // 区域标题
'myplugin_section_callback', // 区域说明的回调函数
'myplugin-settings' // 对应的页面slug
);
// 在区域中添加一个字段
add_settings_field(
'myplugin_field_text', // 字段ID
'示例文本', // 字段标题
'myplugin_field_text_cb', // 字段HTML输出的回调函数
'myplugin-settings', // 页面slug
'myplugin_section_basic' // 区域ID
);
}
add_action( 'admin_init', 'myplugin_settings_init' );
// 区域说明的回调函数
function myplugin_section_callback() {
echo '<p>呢度係插件嘅基礎設定區域。</p>';
}
// 文本字段的回调函数
function myplugin_field_text_cb() {
// 从数据库中获取之前保存的设置值
$options = get_option( 'myplugin_settings' );
$value = $options['myplugin_field_text'] ?? ''; // 使用空合并运算符提供默认值
// 输出HTML输入框
echo '<input type="text" name="myplugin_settings[myplugin_field_text]" value="' . esc_attr( $value ) . '" class="regular-text">';
echo '<p class="description">請輸入一啲示範文字。</p>';
}通過呢種方式保存嘅設定值，可以喺插件代碼嘅任何地方使用 get_option('myplugin_settings') 安全噉攞同用。
插件開發中嘅安全性同最佳實踐
安全性係插件開發中最重要嘅一環。一個唔安全嘅插件可能會成為成個網站嘅漏洞。首要原則係：永遠唔好信任用戶輸入。所有嚟自用戶或者外部源嘅數據，喺進入數據庫、文件系統或者輸出到頁面之前，都必須進行驗證、清理或者轉義。
數據驗證同清理
驗證係檢查輸入數據係咪符合預期格式嘅過程，例如係咪電郵、數字或者喺特定範圍內。WordPress提供咗一系列輔助函數，例如 is_email(), absint()。清理就係喺驗證嘅基礎上，移除數據入面任何非法或者唔安全嘅字符。對於文字欄位，可以用 sanitize_text_field()。
// 在处理表单提交时
$user_input = $_POST['some_field'] ?? ''; // 使用空合并运算符避免未定义索引警告
// 清理输入
$clean_input = sanitize_text_field( $user_input );
// 验证是否是正整数
$clean_id = absint( $_POST['post_id'] );
if ( $clean_id <= 0 ) {
// 处理无效ID的错误
}輸出前嘅數據轉義
轉義係確保數據被安全地輸出到唔同上下文（例如HTML、JavaScript、URL）嘅過程。呢樣對於防止跨站腳本（XSS）攻擊至關重要。WordPress提供咗強大嘅轉義函數：
* esc_html(): 用嚟跳脫HTML內容，防止入面嘅HTML標籤被解析。
* esc_attr(): 用嚟跳脫HTML標籤嘅屬性值。
* esc_url(): 用嚟跳脫URL。
* wp_kses_post(): 容許透過定義好嘅規則集嚟安全輸出部分HTML。
// 在设置页面或前端输出用户数据时
echo '<div class="notice">' . esc_html( $clean_input ) . '</div>';
echo '<input type="hidden" value="' . esc_attr( $clean_input ) . '">';
echo '<a href="/yue/' . esc_url( $user_url ) . '/">連結</a>';
echo wp_kses_post( $allowed_html_content ); // 允许文章级别的HTML标签除此之外，處理資料庫查詢嗰陣，應該要一直用WordPress資料庫類 $wpdb 嘅預處理方法，或者用更高級嘅API好似 WP_Query，佢哋內置咗SQL注入防護。做檔案操作嗰陣，用 wp_upload_dir()、wp_handle_upload() 呢啲API嚟確保路徑安全。
利用鉤子（Hooks）實現高度可擴展性
WordPress插件系統嘅核心係鉤子機制，佢由「動作」同「過濾器」構成。鉤子令插件能夠唔使修改核心代碼嘅情況下，更改WordPress嘅行為或者數據，亦令其他開發者可以擴展你嘅插件。
推薦閱讀 WordPress主題開發入門指南：從零開始構建你嘅第一個自訂主題。
動作鉤子嘅用途同創建
動作鉤子喺特定嘅時間點執行一段代碼，佢唔期望返回值。插件既可以用WordPress提供嘅成千上萬嘅內置鉤子（例如 init, wp_enqueue_scripts, save_post），亦可以創建自己嘅鉤子供其他開發者使用。
掛載到鉤子上嘅代碼如下所示：
// 在文章内容前自动添加一个横幅
function myplugin_prepend_content( $content ) {
if ( is_single() ) {
$custom_text = '<div class="myplugin-banner">呢個係廣告欄。</div>';
$content = $custom_text . $content;
}
return $content;
}
add_filter( 'the_content', 'myplugin_prepend_content' );注意，呢度雖然我哋修改咗內容，但係用嘅係過濾器鉤子 the_content，因為佢要求返回修改後嘅值。
建立自訂動作掛鉤使用 do_action 函數：
// 在你的插件代码中定义一个动作点
function myplugin_complete_task() {
// ... 执行一些任务 ...
// 发出自定义动作，允许其他代码在此处添加功能
do_action( 'myplugin_after_task_complete', $task_id, $result );
}其他插件或主題可以透過 add_action('myplugin_after_task_complete', 'callback', 10, 2) 嚟回應呢個動作。
過濾器掛鉤嘅原理同示例
過濾器掛鈎用喺數據被使用之前修改佢。佢接受一個值，並且必須返回一個（可能被修改過嘅）值。呢個係插件修改文本、選項或者查詢結果嘅常見方式。
使用內置過濾器：
// 修改文章摘要的长度
function myplugin_excerpt_length( $length ) {
return 20; // 将摘要字数限制改为20字
}
add_filter( 'excerpt_length', 'myplugin_excerpt_length' );創建自定義過濾器掛鈎使用 apply_filters 函數：
function myplugin_get_price( $product_id ) {
$base_price = get_post_meta( $product_id, 'price', true );
// 应用过滤器，允许其他代码动态修改价格（例如添加税费、折扣）
$final_price = apply_filters( 'myplugin_product_price', $base_price, $product_id );
return $final_price;
}透過呢種方式，你嘅插件提供咗一個靈活嘅接口，其他開發者可以輕鬆噉修改價格計算邏輯，而唔使直接修改你嘅插件源代碼。
插件國際化同腳本資源管理
一個成熟嘅WordPress插件應該支援國際化，方便被翻譯成唔同語言，同埋妥善管理佢嘅前端同後端嘅CSS、JavaScript資源。
實現插件國際化
國際化係透過使用特定嘅函數包住所有需要翻譯嘅文本字符串嚟實現。呢個涉及兩個主要步驟：使用文本域載入翻譯檔案，同埋喺代碼中標記可翻譯字符串。
首先，喺插件主檔案頭中定義嘅 Text Domain（例如 my-first-plugin）就係你嘅文字區域。然後，喺插件初始化嗰陣（通常喺 init 掛鉤），使用 load_plugin_textdomain 函數嚟載入翻譯文件。
function myplugin_load_textdomain() {
load_plugin_textdomain(
'my-first-plugin', // 文本域，必须与文件头一致
false, // 已弃用参数
dirname( plugin_basename( __FILE__ ) ) . '/languages' // 语言文件存放的相对路径
);
}
add_action( 'init', 'myplugin_load_textdomain' );喺代碼入面，用 __() 嚟翻譯同返回字串，用 _e() 嚟翻譯同直接輸出字串。
$settings_title = __( 'My Plugin Settings', 'my-first-plugin' );
_e( 'Hello World!', 'my-first-plugin' );開發者可以使用 Poedit 等工具從源代碼中提取呢啲字串，生成 .pot 模板檔案，並翻譯成 .po 同埋 .mo 檔案，存放喺插件嘅 /languages/ 目錄下。
正確引入CSS同JavaScript
千祈唔好直接喺PHP檔案入面硬編碼 <link> 或 <script> 用標籤嚟引入資源。WordPress提供咗統一嘅排隊（enqueue）系統嚟管理資源依賴、版本控制同加載時機。
對於後台資源，用 admin_enqueue_scripts 鉤子。
function myplugin_admin_scripts( $hook ) {
// 只在特定插件设置页面加载
if ( $hook != 'toplevel_page_myplugin-settings' ) {
return;
}
wp_enqueue_style(
'myplugin-admin-style', // 句柄
plugins_url( 'css/admin-style.css', __FILE__ ), // 文件URL
array(), // 依赖
'1.0.0' // 版本号，可用于强制浏览器更新缓存
);
wp_enqueue_script(
'myplugin-admin-script',
plugins_url( 'js/admin-script.js', __FILE__ ),
array( 'jquery' ), // 依赖jQuery
'1.0.0',
true // 在页脚加载
);
}
add_action( 'admin_enqueue_scripts', 'myplugin_admin_scripts' );對於前端資源，用 wp_enqueue_scripts 鈎子，其邏輯類似。咁樣確保咗資源加載嘅有序性，避免咗衝突，同埋可以利用瀏覽器快取。
摘要
WordPress插件開發係一個系統性工程，由創建一個符合標準嘅主檔案開始，涵蓋咗後台界面構建、數據安全處理、核心掛鈎運用同國際化支援等多個方面。跟隨最佳實踐，特別係嚴格嘅數據安全規範同對掛鈎機制嘅深入了解，係開發出穩定、安全同可擴展嘅商業級插件嘅關鍵。透過合理使用設定API同管理腳本資源，可以大大提升插件嘅專業性同用戶體驗。開發者應該一直喺程式碼度為翻譯做好準備，以擴闊插件嘅適用範圍。
常見問題
一個最簡單嘅WordPress插件需要包含啲咩元素
一個最簡單嘅插件只需要一個PHP檔案，而且呢個檔案必須包含標準嘅插件頭註解。其中最重要嘅註解行係「Plugin Name」。喺呢個檔案入面，你可以直接編寫PHP程式碼或者透過掛鈎添加功能。
例如，只係包含一個輸出「Hello World」嘅短代碼嘅插件，都只需要咁樣一個檔案就可以運行。
插件點樣同WordPress數據庫互動
建議用返WordPress內置嘅數據庫操作類 $wpdb。佢提供安全嘅數據查詢方法，尤其係佢個 prepare 方法，可以有效防止SQL注入攻擊。
對於大多數數據操作（例如攞文章、操作元數據），更建議使用WordPress嘅高級封裝函數，好似 get_posts(), WP_Query, get_post_meta(), update_post_meta() 等等，呢啲函數喺底層已經處理好安全性同緩存問題。對於自定義數據結構，開發者可以喺插件啟動時創建自定義數據表。
我喺邊度可以搵到所有可用嘅動作同過濾器掛鉤
WordPress官方開發文檔係搵掛鉤嘅最佳去處。另外，開發者亦都可以直接搜索WordPress核心源代碼嚟搵掛鉤。
喺代碼編輯器度打開WordPress嘅根目錄，搵 do_action 或 apply_filters 函數調用，就可以搵到所有定義咗嘅掛鉤同埋佢哋嘅參數。好多網上參考資料都整理咗常用嘅掛鉤列表。
點樣調試我嘅WordPress插件代碼
首先，確保你喺你嘅 wp-config.php 檔案度開咗除錯模式：將 define( 'WP_DEBUG', true );。咁樣就可以顯示PHP錯誤同警告。為咗避免錯誤訊息俾訪客睇到，可以同時設定 define( 'WP_DEBUG_DISPLAY', false ); 並將錯誤記錄到日誌檔案：define( 'WP_DEBUG_LOG', true );。
其次，用 error_log() 函數會將自訂除錯資訊記錄到日誌檔案中。對於複雜嘅數據結構（例如陣列、物件），可以結合 print_r() 或 var_dump() 進行輸出，但務必確保只係管理員登入時先可以查看，以免資訊洩漏。使用專業嘅PHP除錯工具如Xdebug，可以更有效率噉進行斷點除錯同堆疊追蹤。
下一步應該點做?
延伸閱讀及實用知識
以下內容與本文主題相關,適合進一步閱讀。一般而言,最好由與你目前問題最緊密相關的文章開始,然後逐步擴展到周邊主題。