Skip to content

[WordPress] 外掛開發筆記(1) 外掛 (plugin) 介紹

Last Updated on 2021-11-18 by Clay

前言

跟 WordPress 打交道已經邁入第三年，而由於自己對於寫程式、開發新功能一直都抱有強烈的熱忱，所以一直想要要替自己的網站添加些有趣的元件。

但奈何這幾年來實在太忙了，每當這樣開發的熱忱一起，沒過多久又被繁忙的日常生活給壓了下去。直到最近接了外掛開發的案子，這才有時間與理由徹底地學習各式各樣的外掛開發技巧。

本系列文章打算以 WordPress 官方撰寫的 Plugin Handbook 為主，搭配寫範例程式碼中所查詢的各種資料彙整成的筆記。

看過網路上的開發外掛的前輩寫說，不喜歡寫這樣的筆記文章，感覺自己很像是翻譯的搬運工。

沒有唱反調的意思，但我抱持著相反的意見。

撰寫筆記文章，是為了不夠成熟的自己，讓自己在吸收知識的過程中能盡量理解那些程式運作的原理。而另一方面，又可說是為了別人：誰說沒有需要這些翻譯文章的新學朋友呢？

所以以下，我將依循著官方的手冊，一部部紀錄如何寫一個屬於自己的外掛（plugin）。

外掛（plugin）開發介紹

為什麼我們需要開發外掛（plugin）呢？最主要的原因就是因為 WordPress 開發者的的主要核心觀念即為：不要動 WordPress 的核心（Don't touch WordPress core）。

透過外掛的執行，我們可以在不修改 WordPress 核心的狀況下去製作我們的功能，即便外掛崩潰、失敗了，我們也能透過卸載外掛來還原網站的運作。

如此一來，我們的網站就會一直都是安全可運行的。

如何製作一個外掛

官方手冊提到了 Hello Dolly 這樣一個外掛，宣稱它是一個最基本、簡單的外掛，只有一百行。（即便它的官方首頁上宣稱自己並非是個外掛。）

一個最基本的外掛，只需要：

  • 外掛標頭（plugin header）
  • 一些 PHP 函式
  • 一些 WordPress 所提供的鉤子（hook）

以下一步步介紹如何製作第一個外掛。


Step 1: 建立外掛標頭

標頭（header）是一個外掛的基本資料，會反映在 wp-admin 的外掛頁面當中。

不過首先，我們得先建立起我們的外掛。以下操作開始轉為終端機。

前往網站後台 wp-content/plugins/，並建立自己想要的外掛名稱資料夾，並在底下建立一個與資料夾名稱相同的 PHP 檔。

mkdir wp-content/plugins/"plugin-name"
vim wp-content/plugins/"plugin-name"/"plugin-name.php"


vim 可以換成任何你習慣的編輯器。

接著我們開始編輯外掛的標頭。外掛標頭至少需要包含 Plugin Name 這個欄位。

標頭欄位欄位說明
Plugin Name外掛的名稱，會顯示在 wp-admin 後台
Plugin URI外掛的主頁，不應在此處使用 wordpress.org 的頁面，而是你自己的外掛介紹網頁
Description簡單地描述此外掛，會顯示在 wp-admin 後台
Version當前外掛版本號，比如說 1.0.3
Requires at least最低支援的 WordPress 版本
Requires PHP最低支援的 PHP 版本
Author開發者，可以使用 , 列出多名作者
Author URI作者的網站或資訊
License套件授權（許可）的類型
License URILicense 完整文件的連結
Text Domain外掛的文本域，參考 Text Domain
Domain Path指向不同語言翻譯的路徑
Network外掛是否需要網路（true 或省略）
Update URI允許第三方外掛，以避免被 WordPress.org 外掛目錄中同名外掛的更新意外覆蓋


以上的 URI 指的是 Uniform Resource Identifier，跟 URL (Uniform Resource Locator) 不同。


以下是個範例標頭。

<?php
/**
 * Plugin Name:       Test Plugin
 * Plugin URI:        https://example.com/plugins/the-basics/
 * Description:       This is a test plugin.
 * Version:           0.0.1
 * Requires at least: 5.2
 * Requires PHP:      7.2
 * Author:            Clay Atlas
 * Author URI:        https://clay-atlas.com
 * License:           GPL v2
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Update URI:        https://example.com/my-plugin/
 * Text Domain:       my-basic-plugin
 * Domain Path:       /languages
 */
?


儲存好標頭之後，你應該可以在自己 wp-admin 後台的外掛頁面中，看到以下 Test Plugin 的外掛。

不過由於我們什麼內容都還沒撰寫，所以先別啟用。


Step 2: 激活/反激活你的外掛（activation/deactivation）

這裡我們需要介紹三個基本的鉤子（hook）：

  • register_activation_hook(): 當使用者激活外掛時執行，你將會使用其來設置外掛。比方說，在設定欄位中建立一些 options。
  • register_deactivation_hook(): 當使用者反激活外掛時執行，通常用於清除外掛儲存的任何臨時資料。
  • register_uninstall_hook(): 當使用者選擇 delete 時運作，可以使用其來刪除任何添加到 options 中的資料。

（備註：deactivation 經常與 uninstall 搞混，前者可能只是暫時地停用外掛、後者則是徹底刪除了外掛）

官方給予了個簡潔又有清晰的範例程式碼，在這裡我們直接寫在含有標頭檔的 PHP 檔案裡。

順帶一提會了增進展示的介面效果，我順便連內建的書本圖示都用上了。

<?php
/**
 * Plugin Name:       Test Plugin
 * Plugin URI:        https://example.com/plugins/the-basics/
 * Description:       This is a test plugin.
 * Version:           0.0.1
 * Requires at least: 5.2
 * Requires PHP:      7.2
 * Author:            Clay Atlas
 * Author URI:        https://clay-atlas.com
 * License:           GPL v2
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Update URI:        https://example.com/my-plugin/
 * Text Domain:       my-basic-plugin
 * Domain Path:       /languages
 */

/**
 * Register the "book" custom post type.
 */
function pluginprefix_setup_post_type() {
    register_post_type( 'book', [
        'pulbic' => true,
        'show_ui' => true,
        'menu_icon' => 'dashicons-book',
        'labels' => [
            'name' => 'Books'
        ]
    ] );
}
add_action( 'init', 'pluginprefix_setup_post_type' );


/**
 * Activate the plugin.
 */
function pluginprefix_activate() {
    // Trigger our function that registers the csutom post type plugin.
    pluginprefix_setup_post_type();

    // Clear the permalinks after the post type has been registered.
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'pluginprefix_activate' );



/**
 * Deactivation hook
 */
function pluginprefix_deactivate() {
    // Unregister the post type, so the rules are no longer in memory.
    unregister_post_type( 'book' );

    // Clear the permalinks to remove our post type's rules from the database.
    flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'pluginprefix_deactivate' );

?>


Output:

這裡有幾個第一次出現的函式，做點簡單的介紹：

  • register_post_type(): 不應在 init 操作前註冊發布類型。簡單來講就是可以透過此函式建立我們自己的發布類型。預設的發布類型有兩種：文章與頁面。如果今天你希望能夠讓網站管理員或使用者發布『跑馬燈』的資訊，就可以利用這個函式建立一種可管理的發布類型。
  • unregister_post_type(): 跟上面的函式相反，這是取消註冊我們建立的發布類型。
  • flush_rewrite_rules(): 刪除重寫規則並重新建立重寫規則，最適合放置於激活、反激活外掛的時間點
  • __FILE__: 返回正在執行的 PHP 文件完整路徑與名稱。


Step 3: 卸載方法（Uninstall Methods）

當使用者要從網站卸載掉外掛時，我們的外掛可能需要做一些清理的步驟。

而卸載方式又有兩種，一種是使用 register_uninstall_hook() 來完成。比方說：

register_uninstall_hook(__FILE__, 'pluginprefix_function_to_run');


而我們要清理掉的一些資料，就將程式寫在 pluginprefix_function_to_run() 裡頭。

而另一種方法，則是在外掛根目錄新增一個 uninstall.php 的檔案。

// if uninstall.php is not called by WordPress, die
if (!defined('WP_UNINSTALL_PLUGIN')) {
    die;
}
 
$option_name = 'wporg_option';
 
delete_option($option_name);
 
// for site options in Multisite
delete_site_option($option_name);
 
// drop a custom database table
global $wpdb;
$wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}mytable");


至此，我們已經走過了一個外掛從建立、激活、反激活、刪除等一整個完整的週期了。以上就是最基本的 WordPress 外掛建立介紹。

References

Read More

  • [WordPress] 外掛開發筆記(1) 外掛 (plugin) 介紹
Tags:

Leave a Reply