準備工作與環境搭建
在開始編寫代碼之前，你需要確保擁有一個合適的開發環境。這包括一個本地的 WordPress 安裝和一個代碼編輯器。本地環境可以讓你在不影響線上網站的情況下自由測試和調試。常用的本地開發環境軟件有 Local by Flywheel、XAMPP 或 MAMP。
你需要為你的插件想一個唯一的名稱，這個名稱將被用作插件的主目錄名和主文件名。例如，如果你的插件叫做“Hello World”，那麼你的主插件文件可以命名為 hello-world.php。確保你的插件名稱和描述在 WordPress 插件目錄中是獨一無二的，這能有效避免與其他插件衝突。
此外，熟悉 WordPress 的官方開發手冊和代碼參考是至關重要的。瞭解 WordPress 的核心概念，如動作鈎子（Action Hooks）、過濾器鈎子（Filter Hooks）、短代碼（Shortcodes）和設置 API，將為你的開發奠定堅實基礎。
推荐阅读 WordPress插件开发全攻略：从零开始打造专业PHP插件。
創建第一個插件文件
插件的核心是一個或多個 PHP 文件。最簡單的情況下，一個插件可以只由一個 PHP 文件構成。為了創建一個有效的插件，你需要在主插件文件的頭部添加標準的插件信息註釋。這個註釋塊會告訴 WordPress 關於你的插件的所有元信息，如名稱、描述、版本、作者等。
編寫插件頭部信息
WordPress 通過讀取文件頂部的特定格式的註釋來識別和顯示插件信息。下面是一個最基本的插件頭部示例：
<?php
/**
* Plugin Name: 我的第一个插件
* Plugin URI: https://example.com/my-first-plugin
* Description: 这是一个用于学习和演示的简单 WordPress 插件。
* Version: 1.0.0
* Requires at least: 5.2
* Requires PHP: 7.2
* Author: 你的名字
* Author URI: https://example.com
* License: GPL v2 or later
* Text Domain: my-first-plugin
* Domain Path: /languages
*/將這段代碼保存為一個新的 PHP 文件，例如 my-first-plugin.php。然後，將這個文件放入你本地 WordPress 安裝目錄的 wp-content/plugins 文件夾中。此時，進入 WordPress 後台的“插件”頁面，你應該能看到一個名為“我的第一個插件”的新插件出現在列表中，並可以激活它。目前它還沒有任何功能。
為插件添加基礎功能
激活插件後，我們將為其添加一個簡單的功能：在文章內容的末尾自動添加一段自定義文本。這需要用到 WordPress 的過濾器鈎子 the_content。
你可以將以下代碼添加到剛才的插件頭部信息下方：
推荐阅读 從零開始：WordPress插件開發全流程詳解。
/**
* 在文章内容末尾添加自定义文本
*
* @param string $content 当前文章内容。
* @return string 修改后的文章内容。
*/
function mfp_add_footer_text( $content ) {
// 仅针对主循环中的单个文章页面
if ( is_single() && in_the_loop() && is_main_query() ) {
$custom_text = '<p><em>感谢您阅读这篇文章，由“我的第一个插件”呈现。</em></p>';
$content .= $custom_text;
}
return $content;
}
// 将自定义函数挂载到 `the_content` 过滤器上
add_filter( 'the_content', 'mfp_add_footer_text' );這段代碼定義了一個名為 mfp_add_footer_text 的函數，它接收文章內容 $content 作為參數。函數內部首先使用條件標籤（is_single(), in_the_loop(), is_main_query()）來確保我們只在單個文章頁面的主循環中修改內容，避免影響其他頁面如首頁、存檔頁。然後，它創建一段自定義的 HTML 文本，並將其附加到原文內容之後。最後，通過 add_filter 函數將這個自定義函數“掛載”到 WordPress 的 the_content 過濾器上。
保存文件後，刷新前端的一篇文章頁面，你將在文章正文的末尾看到添加的文本。
開發進階功能：創建管理菜單與選項頁
一個功能完善的插件通常需要與管理員交互，這通常通過在後端添加設置頁面來實現。WordPress 提供了豐富的 API 來創建管理菜單和選項頁。
在後台添加插件菜單項
我們將為插件創建一個獨立的管理菜單頁面，用於配置一些選項。這需要使用 add_action 鈎子和 admin_menu 動作。
在你的插件主文件中繼續添加以下代碼：
/**
* 在 WordPress 后台管理菜单中添加一个新的顶级菜单项
*/
function mfp_register_admin_menu() {
add_menu_page(
'我的插件设置', // 页面标题
'我的插件', // 菜单标题
'manage_options', // 所需权限
'my-first-plugin', // 菜单 slug
'mfp_render_settings_page', // 渲染页面的回调函数
'dashicons-admin-plugins', // 图标（可选）
80 // 菜单位置
);
}
add_action( 'admin_menu', 'mfp_register_admin_menu' );add_menu_page 函數用於註冊一個新的頂級菜單。其中，manage_options 是一個權限標識，意味着只有具有“管理選項”權限的用户（通常是管理員）才能看到這個菜單。mfp_render_settings_page 是我們接下來要定義的、用於輸出設置頁面 HTML 內容的函數名。
推荐阅读 WordPress 外掛開發終極指南：從零建構你的第一個自訂外掛。
構建設置頁面的內容
現在，我們需要定義上面提到的回調函數 mfp_render_settings_page 來渲染一個簡單的設置頁面。
/**
* 渲染插件设置页面的内容
*/
function mfp_render_settings_page() {
?>
<div class="wrap">
<h1></h1>
<form action="/zh-hk/options.php/" method="post" data-trp-original-action="options.php">
<?php
// 输出设置字段、安全 nonce 字段等
settings_fields( 'mfp_settings_group' );
do_settings_sections( 'my-first-plugin' );
submit_button( '保存设置' );
?>
<input type="hidden" name="trp-form-language" value="zh-hk"/></form>
</div>
<?php
}這個函數輸出了一個基本的 WordPress 管理頁面結構，包含標題和一個表單。它使用了 WordPress 設置 API 的兩個核心函數：settings_fields 以及 do_settings_sections。為了使其工作，我們還需要註冊設置、節和字段。
使用設置 API 註冊選項
WordPress 設置 API 提供了一種安全、標準化的方式來處理表單選項的註冊、保存和驗證。我們繼續添加以下代碼來註冊一個簡單的文本字段。
/**
* 初始化插件的设置
*/
function mfp_settings_init() {
// 注册一个新的设置项 `mfp_options` 到数据库
register_setting( 'mfp_settings_group', 'mfp_options' );
// 在页面内添加一个新的节
add_settings_section(
'mfp_section_basic',
'基础设置',
'mfp_section_basic_callback',
'my-first-plugin'
);
// 向节中添加一个字段
add_settings_field(
'mfp_field_custom_text',
'自定义页脚文本',
'mfp_field_custom_text_callback',
'my-first-plugin',
'mfp_section_basic',
array( 'label_for' => 'mfp_field_custom_text' )
);
}
add_action( 'admin_init', 'mfp_settings_init' );
/**
* 节描述的回调函数（可以为空）
*/
function mfp_section_basic_callback() {
echo '<p>在这里配置插件的基础选项。</p>';
}
/**
* 字段 `mfp_field_custom_text` 的回调函数，用于输出 HTML 输入框
*/
function mfp_field_custom_text_callback() {
// 从数据库获取现有值
$options = get_option( 'mfp_options' );
$value = isset( $options['custom_text'] ) ? $options['custom_text'] : '';
?>
<input type="text"
id="mfp_field_custom_text"
name="mfp_options[custom_text]"
value="<?php echo esc_attr( $value ); ?>"
class="regular-text" />
<p class="description">这段文字将显示在文章末尾。</p>
<?php
}現在，我們需要修改之前的 mfp_add_footer_text 函數，讓它使用我們新創建的選項值，而不是硬編碼的文本。
function mfp_add_footer_text( $content ) {
if ( is_single() && in_the_loop() && is_main_query() ) {
$options = get_option( 'mfp_options' );
$custom_text = isset( $options['custom_text'] ) ? $options['custom_text'] : '';
if ( ! empty( $custom_text ) ) {
$content .= '<p><em>' . esc_html( $custom_text ) . '</em></p>';
}
}
return $content;
}至此，你的插件擁有了一個完整的後台設置頁面。管理員可以在“我的插件”菜單下找到設置頁，輸入自定義的頁腳文本，並保存。這個文本將動態地顯示在網站前端的文章末尾。
插件優化與安全實踐
開發插件時，遵循最佳實踐對於安全性、性能和維護性至關重要。這裏介紹幾個核心原則。
確保代碼安全
所有從前端或管理界面接收到的數據，在輸出到瀏覽器或存入數據庫之前，都必須進行驗證、清理和轉義。這可以防止跨站腳本（XSS）和 SQL 注入等安全漏洞。
- 轉義輸出：使用函數如
esc_html(),esc_attr(),esc_url(),wp_kses_post()來轉義動態內容。 - 清理輸入：使用函數如
sanitize_text_field(),sanitize_email(),intval()來處理用户提交的表單數據。 - 權限檢查：在管理員回調函數中，使用
current_user_can()進行二次權限確認。在涉及數據修改的 AJAX 或 REST API 端點，務必使用 nonce（數字令牌）進行驗證。
遵循 WordPress 的编码标准
採用 WordPress 編碼標準可以確保你的代碼風格與核心代碼一致，提高可讀性，並方便其他開發者協作。這包括使用正確的縮進、括號風格、命名約定（函數和變量使用小寫字母加下劃線）等。你可以使用 PHP CodeSniffer 配合 WordPress 標準規則來自動檢查代碼。
實現國際化支持
從一開始就為你的插件添加國際化支持，可以讓全世界的用户輕鬆地將其翻譯成自己的語言。這主要通過以下步驟實現：
1. 在插件頭部註釋中正確設置 Text Domain 以及 Domain Path。
2. 在所有需要翻譯的字符串周圍使用 WordPress 的翻譯函數，如 (), _e(), esc_html() 等等。
3. 使用工具如 Poedit 來生成 .pot 模板文件，供译者创建使用。 .po 以及 .mo 翻譯文件。
例如，將設置頁的描述文字國際化：
function mfp_section_basic_callback() {
echo '<p>' . esc_html__( '在这里配置插件的基础选项。', 'my-first-plugin' ) . '</p>';
}总结
本文從零開始，引導你完成了創建一個基礎但功能完整的 WordPress 插件的全過程。我們涵蓋了從環境準備、創建插件文件、編寫插件頭部信息，到使用動作鈎子和過濾器鈎子為文章添加內容，再到使用 WordPress 設置 API 構建複雜的後台管理界面。最後，我們探討了插件開發中至關重要的安全、編碼標準和國際化等優化實踐。
通過這個實踐，你應該已經掌握了 WordPress 插件開發的核心流程和基本工具。下一步，你可以嘗試開發更復雜的功能，如創建自定義文章類型、自定義數據庫表、使用 jQuery 增強交互，或者將你的插件提交到 WordPress 官方插件目錄。記住，持續學習和閲讀核心代碼是提升開發技能的最佳途徑。
常见问题解答（FAQ）
如何調試我的 WordPress 插件？
啓用 WordPress 的調試模式是首要步驟。在你的 wp-config.php 文件中，将…… WP_DEBUG 常量被设置为： true。這將直接在頁面上顯示 PHP 錯誤、警告和通知。
同時，可以使用 error_log() 函數將自定義調試信息寫入服務器的錯誤日誌，或者使用瀏覽器的開發者工具（控制枱和網絡選項卡）來調試 JavaScript 和 AJAX 請求。對於複雜的邏輯，使用如 Xdebug 等專業調試工具會事半功倍。
我的插件會和主題或其他插件衝突嗎？
有可能，尤其是在處理相同的鈎子、使用通用的全局變量名或類名時。為了最大程度減少衝突，請務必為你的所有函數、類、變量和選項名添加唯一的前綴。例如，不要使用 add_footer_text，而是使用類似 myplugin_add_footer_text 的名稱。
在修改全局內容（如查詢變量）之前，進行充分的檢查和條件限制。在發佈前，儘可能多地在不同環境和不同主題組合下測試你的插件。
我需要學習哪些技術來開發高級插件？
除了紮實的 PHP 基礎，你還需要深入瞭解：
- JavaScript：用於前端交互和 WordPress 定製器開發。
- jQuery：儘管 WordPress 正在向現代 JS 框架過渡，但 jQuery 仍被廣泛使用。
- REST API：用於創建解耦的前端應用或與外部服務交互。
- 數據庫知識：瞭解 WordPress 的數據庫結構，以及如何安全地進行自定義查詢或創建新表。
- Composer：用於管理 PHP 依賴包。
- 構建工具：如 Webpack，用於管理現代 JavaScript 和 SASS 的編譯。
如何將我的插件發佈到 WordPress 官方目錄？
首先，確保你的插件完全符合官方的插件開發指南和安全最佳實踐。你需要一個 WordPress.org 賬號。在賬號下提交你的插件壓縮包進行審核。審核過程會檢查代碼質量、安全性、許可證（必須是 GPL 兼容）等。
如果你的插件通過審核，它將被添加到 SVN 倉庫中，你可以通過 SVN 來更新和維護你的插件。發佈後，用户就可以直接在他們的 WordPress 後台搜索、安裝和更新你的插件了。
接下来，我该怎么做呢？
延伸阅读与实用知识
下方这些内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始看起，然后再逐步扩展到相关主题，这样通常效果会更好。