WordPress 插件開發基礎
WordPress 插件係擴展 WordPress 核心功能嘅獨立 PHP 腳本集合。佢哋容許開發者喺唔修改 WordPress 核心文件嘅前提下，為網站添加新功能或修改現有行為。一個插件可以簡單到只有一個文件，亦可以係一個包含多個文件、腳本同樣式表嘅複雜目錄。
理解插件嘅基本結構
一個插件最核心嘅文件係主插件文件。呢個文件必須包含一個特定嘅插件頭註釋，WordPress 透過佢嚟識別你嘅插件。插件頭通常位於文件頂部，包含例如插件名稱、描述、版本、作者等資訊。例如，一個名為「我嘅問候插件」嘅主文件 my-greeting-plugin.php 嘅开头可能如下所示：
<?php
/**
* Plugin Name: 我的问候插件
* Plugin URI: https://example.com/my-greeting-plugin
* Description: 一个简单的插件，用于在网站前台显示问候语。
* Version: 1.0.0
* Author: 开发者名称
* License: GPL v2 or later
* Text Domain: my-greeting-plugin
*/插件頭之後，你就可以開始編寫插件嘅功能代碼喇。所有插件代碼都應該包裝喺條件語句中，以防止直接存取導致安全問題，並確保只喺 WordPress 環境中執行。
推薦閱讀 從零開始：整你第一個WordPress插件。
外掛目錄同檔案組織
對於功能簡單嘅插件，一個 PHP 檔案可能就足夠。但隨住功能增加，良好嘅檔案組織至關重要。一個典型嘅插件目錄可能包含以下結構：
- my-plugin/ （主目錄）
- my-plugin.php （主插件檔案）
- uninstall.php （卸載處理腳本）
- includes/ （存放核心功能類或函數嘅目錄）
- admin/ （存放後台管理相關代碼嘅目錄）
- public/ （存放網站前台相關代碼嘅目錄）
- assets/ （存放 JavaScript、CSS 同圖片資源嘅目錄）
- languages/ （存放國際化翻譯文件嘅目錄）
呢種模組化結構令代碼更加易於維護、測試同協作。
核心開發概念：掛鈎同過濾器
WordPress 插件開發嘅核心係「掛鉤」（Hooks）系統。掛鉤容許你喺 WordPress 執行嘅特定點插入自己嘅代碼，從而改變或者增強默認行為。掛鉤分為兩種主要類型：動作掛鉤（Action Hooks）同過濾器掛鉤（Filter Hooks）。
使用動作鈎子添加功能
動作掛鉤喺特定事件發生時執行，例如發佈文章、用戶登入或者載入管理頁面。佢哋唔會傳返任何值畀調用者，而係用嚟「執行一個動作」。你可以使用 add_action() 函數將自己嘅函數「掛載」到一個動作鉤上面。
例如，如果你想喺網站嘅前台頁腳加一段自訂文字，可以用 wp_footer 呢個動作鉤。喺插件主檔案入面，你可以咁寫：
推薦閱讀 WordPress插件開發終極指南：由零到一建立自訂功能擴充。
function myplugin_add_footer_text() {
echo '<p style="text-align:center;">多謝使用呢個網站！</p>';
}
add_action( 'wp_footer', 'myplugin_add_footer_text' );當 WordPress 執行到 wp_footer 位置嗰陣，就會自動調用你註冊嘅 myplugin_add_footer_text 函數。
用過濾器鈎修改內容
過濾器掛鈎用嚟修改數據。佢哋喺數據被傳送到數據庫或者瀏覽器之前，俾機會你修改佢。過濾器函數必須返回修改後嘅值。使用 add_filter() 用函數嚟註冊過濾器。
一個常見嘅例子係修改文章標題。假設你想喺所有文章標題後面自動加個商標符號™，可以用 the_title 過濾器：
function myplugin_modify_post_title( $title, $post_id ) {
// 确保只在主循环且不是管理后台中修改
if ( ! is_admin() && in_the_loop() ) {
$title = $title . ' ™';
}
return $title;
}
add_filter( 'the_title', 'myplugin_modify_post_title', 10, 2 );呢度嘅參數 10 係優先級（數字愈細愈優先執行），2 表示我哋嘅回調函數接受兩個參數（$title 同埋 $post_id）。
創建插件管理頁面
好多插件需要喺WordPress管理後台提供一個設定頁面，等用戶可以設定選項。WordPress提供咗豐富嘅API嚟創建頂級選單同子選單。
添加頂級管理選單
你可以用 add_menu_page() 函數為你嘅插件創建一個獨立嘅管理選單。呢個函數需要多個參數，包括頁面標題、選單標題、用戶權限、選單別名、回調函數等。
推薦閱讀 WordPress 插件開發完全指南：從入門到精通實戰教程。
以下代碼展示咗點樣添加一個簡單嘅頂級選單頁面：
function myplugin_add_admin_menu() {
add_menu_page(
'我的插件设置', // 页面标题
'我的插件', // 菜单标题
'manage_options', // 所需权限（管理员）
'myplugin-settings', // 菜单别名（URL中的slug）
'myplugin_settings_page', // 用于输出页面内容的回调函数
'dashicons-admin-generic', // 菜单图标（使用Dashicons）
30 // 菜单位置
);
}
add_action( 'admin_menu', 'myplugin_add_admin_menu' );
// 定义输出页面内容的回调函数
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
// 输出设置字段和安全 nonce 字段
settings_fields( 'myplugin_options' );
do_settings_sections( 'myplugin-settings' );
submit_button( '保存设置' );
?>
<input type="hidden" name="trp-form-language" value="yue"/></form>
</div>
<?php
}使用設定 API 創建選項
手動處理表單提交同驗證係繁瑣而且唔安全。WordPress 設定 API 提供咗一種標準化嘅方式嚟註冊、驗證同保存設定。佢涉及三個主要函數：register_setting()、add_settings_section() 同埋 add_settings_field()。
下面嘅示例示範咗點樣註冊一個設定組同一個文字欄位：
function myplugin_settings_init() {
// 注册一个新的设置组 “myplugin_options” 到 “reading” 页面（这里我们用自己的页面）
register_setting(
'myplugin-settings', // 选项组，通常与页面别名一致
'myplugin_options', // 存储在 wp_options 表中的选项名
'myplugin_sanitize_callback' // 可选的清理回调函数
);
// 在页面中添加一个区域
add_settings_section(
'myplugin_section_main', // 区域的ID
'主要设置', // 区域标题
'myplugin_section_callback', // 区域描述的回调函数
'myplugin-settings' // 页面别名
);
// 向区域中添加一个字段
add_settings_field(
'myplugin_field_greeting', // 字段ID
'问候语', // 字段标签
'myplugin_field_greeting_callback', // 用于输出字段HTML的回调函数
'myplugin-settings', // 页面别名
'myplugin_section_main', // 区域ID
[ 'label_for' => 'myplugin_field_greeting' ] // 额外参数
);
}
add_action( 'admin_init', 'myplugin_settings_init' );
// 字段HTML的回调函数
function myplugin_field_greeting_callback() {
$options = get_option( 'myplugin_options' );
$value = isset( $options['greeting'] ) ? $options['greeting'] : '你好，世界！';
echo '<input type="text" id="myplugin_field_greeting" name="myplugin_options[greeting]" value="' . esc_attr( $value ) . '" class="regular-text" />';
}插件安全同最佳實踐
開發一個受歡迎嘅外掛程式，安全性同程式碼質素係重中之重。唔安全嘅外掛程式可能成為網站被攻擊嘅入口。
數據驗證、清理同轉義
千祈唔好信任用戶輸入或者嚟自資料庫嘅數據。喺處理任何數據之前，必須進行驗證（Validation）、清理（Sanitization）同轉義（Escaping）。
- 驗證：檢查數據係咪符合預期嘅格式或規則（例如係咪電郵、數字等）。使用嘅函數如
is_email()、ctype_digit()或者正則表達式。 - 清理：喺將數據保存到數據庫或者用喺其他操作之前，移除其中唔安全或者唔需要嘅部分。對於唔同嘅數據，使用對應嘅清理函數，例如
sanitize_text_field()（用喺文本）、sanitize_email()（用喺電郵）、intval()（用喺整數）。 - 轉義：當將數據輸出到 HTML、JavaScript 或 URL 時，要確保佢哋被安全編碼，防止跨站腳本（XSS）攻擊。使用函數例如
esc_html()、esc_attr()、esc_url()同埋wp_kses()。
例如，喺保存同輸出我哋之前創建嘅問候語選項時：
// 在保存设置时的清理回调函数中
function myplugin_sanitize_callback( $input ) {
$sanitized = [];
if ( isset( $input['greeting'] ) ) {
// 清理文本输入
$sanitized['greeting'] = sanitize_text_field( $input['greeting'] );
}
return $sanitized;
}
// 在前台输出问候语时
function myplugin_display_greeting() {
$options = get_option( 'myplugin_options' );
$greeting = isset( $options['greeting'] ) ? $options['greeting'] : '你好，世界！';
// 在输出到HTML前进行转义
echo '<div class="greeting">' . esc_html( $問候 ) . '</div>';
}實現國際化支援
為咗你嘅插件可以俾全世界嘅用戶使用，必須支援國際化（i18n）。呢個意味住所有面向用戶嘅字串都應該包裝喺翻譯函數入面，方便翻譯成其他語言。
WordPress 用咗 GNU gettext 框架。核心嘅翻譯函數係 __()（用嚟攞翻譯好嘅字串）同 _e()（用嚟輸出翻譯好嘅字串）。你需要為你嘅插件設定一個獨一無二嘅文本域（Text Domain），呢個文本域喺插件頭已經定義過。
喺代碼入面，你應該咁樣用：
// 获取翻译后的字符串并赋值给变量
$message = __( '感谢你使用我的插件！', 'my-greeting-plugin' );
// 直接输出翻译后的字符串
_e( '设置已成功保存。', 'my-greeting-plugin' );
// 带占位符的翻译
printf(
__( '欢迎，%s！', 'my-greeting-plugin' ),
esc_html( $username )
);跟住，你可以用好似 Poedit 咁嘅工具，由程式碼度抽出呢啲字串生成 .pot 模板文件，翻譯人員可以根據呢個創建唔同語言嘅 .po 同埋 .mo 檔案，同擺喺插件嘅 /languages/ 目錄下。
摘要
WordPress 插件開發係一個好強大同靈活嘅領域，佢容許開發者深度定制同擴展 WordPress。由理解基本嘅插件結構同掛鉤系統開始，到建立互動式嘅管理介面，再跟住嚴格嘅安全同國際化最佳實踐，每一步都係建立高質素、可維護同受歡迎插件嘅關鍵。記住，核心在於利用 WordPress 提供嘅豐富 API，而唔係繞過佢。透過模組化組織程式碼、嚴格處理數據、同埋由一開始就考慮多語言支援，你嘅插件將會唔單止功能強大，而且安全、專業，同埋有全球化嘅潛力。
常見問題
一個 WordPress 插件最少需要幾個檔案？
一個插件最少只需要一個 PHP 檔案。只要呢個檔案包含咗正確嘅插件頭註釋（Plugin Header Comment），WordPress 就能夠喺後台嘅插件列表度識別同啟動佢。呢個單一嘅檔案可以包含插件嘅所有程式碼。
點樣防止插件名同其他插件撞名？
為咗防止函數名、類名或者常量名同其他插件或者主題撞名，你應該用一個獨特嘅前綴。通常呢個前綴可以基於你嘅插件名或者縮寫。例如，如果你嘅插件叫「Awesome Slider」，你可以用 as_ 或 awesome_slider_ 作為所有函數同類嘅前綴。對於類名，可以考慮用更獨特嘅命名空間式結構。
插件卸載嗰陣點樣清理數據庫入面嘅數據？
WordPress 提供咗兩種方式去處理插件卸載時嘅清理工作。第一種係註冊一個卸載掛鈎，喺你嘅主插件檔案入面，透過 register_uninstall_hook() 函數指定一個回調函數去刪除插件創建嘅資料表同選項。第二種，亦係更推薦嘅方式，係創建一個獨立嘅 uninstall.php 檔案。當用戶透過 WordPress 後台刪除插件嗰陣，WordPress 會自動執行呢個檔案入面嘅代碼。喺呢個檔案入面，你需要檢查常數 WP_UNINSTALL_PLUGIN 有冇被定義，然後安全噉刪除所有插件資料。
我應該點樣為我嘅插件加入 JavaScript 同 CSS 檔案？
你應該使用 WordPress 提供嘅隊列函數去正確噉加入腳本同埋樣式表，唔好直接喺 HTML 度輸出 <script> 或 <link> 標籤。對於前端資源，用 wp_enqueue_script() 同埋 wp_enqueue_style() 功能,並將佢哋安裝到 wp_enqueue_scripts 動作鉤子上。對於管理後台嘅資源，就掛載到 admin_enqueue_scripts 掛喺個鉤上面。咁樣可以確保啲依賴關係處理得啱，同埋避免重複載入同一樣資源。
開發外掛時點樣進行調試？
首先，確保你喺你嘅 wp-config.php 文件度開啟 WordPress 除錯模式。將 WP_DEBUG 常數設定為 true。你仲可以同時開啟 WP_DEBUG_LOG（將錯誤記錄落檔案）同 WP_DEBUG_DISPLAY（喺螢幕度顯示錯誤）。用 error_log() 函數將自訂嘅除錯資訊記錄到伺服器嘅錯誤日誌度。另外，利用瀏覽器開發者工具嘅控制台同埋網絡面板嚟除錯 JavaScript 同埋 AJAX 請求。對於複雜嘅邏輯，可以考慮用 Xdebug 呢類專業嘅 PHP 除錯工具。
下一步應該點做?
延伸閱讀及實用知識
以下內容與本文主題相關,適合進一步閱讀。一般而言,最好由與你目前問題最緊密相關的文章開始,然後逐步擴展到周邊主題。