本文主要介紹，如何為外掛作品建立一個選單入口，以及產生一個設定的頁面。文中提及 Hook 的部份因需要較長篇幅，會放在 Day 28 會專文介紹。

在上一篇文章介紹完 WordPress 的程式碼風格後，今天開始會大量接觸 WordPress 的函式 (function)、類別 (class)、及 WordPress 的事件驅動架構 Hook 。因此我們會需要用到可以隨時查詢相關用的文件網站。

程式碼文件網站

（圖 A：WordPress 程式碼文件網站）

網址是：https://developer.wordpress.org/reference/

在本系列文章提及的函式會特別介紹。比較要注意的是，WordPress 的函式採 Snake Case 命名法，和 PHP 原生函式是相同命名法，萬一在範例中有看到不認識的函式，可以在這個網站查詢，確定一下是 WordPress 函式還是 PHP 原生函式。通常在各個函式文件的下方會有熱心的開發者提供範例。

功能規劃

由於這只是一個小作品，用在這次的鐵人賽教學用，所以架構盡量簡單。功能也很單純，就只是把頁面文章內容快取起來，TTL 設為 24 小時。如果文章在後台有更新的話，則刪除該文章的快取資料。如此一來大幅度減少對資料庫的存取次數。

主要功能

主要功能邏輯歸納如下：

• (A) 當使用者瀏覽文章網頁，如果沒有快取，則存進快取。
• (B) 當使用者瀏覽文章網頁，如果有快取的話，不透過資料庫，直接從快取取得。
• (C) TTL 為 88600 秒，也就是 24 小時。過期的話，則刪除快取，回到流程 A

設定選項

從主要功能來看，目前先規劃可以讓使用者可以設定的選項如下：

• 快取的驅動程式：Sample Cache 套件可以用的 8 個 Driver 都放進去。
• 快取有效時間 (TTL)：預設 86400 秒（24 小時）。

檔案結構

設計外掛時，一開始不要想著要開多少功能，而是先做出來，再慢慢加上去。根據如上述的規劃，檔案結構也非常的簡潔。其中 admin 這個目錄存放的是當使用者進到後台時才會載入的檔案。

.                                 
├── LICENSE                       
├── README.md                     
├── README.txt                              
├── cache-master.php              
├── composer.json                                
├── inc                           
│   ├── admin                     
│   │   ├── menu.php              
│   │   ├── register.php          
│   │   └── setting.php           
│   ├── autoload.php              
│   └── class-cache-master.php    
├── languages                     
├── phpcs.xml                     
└── vendor                        

結構說明：

有了以上的初步規劃後可以開始設計選單入可及設定的頁面了。

實作初始化檔案

範例：/day-27/cache-master/cache-master.php

（圖 B：cache-master.php 程式碼截圖）

昨天完成的初始化檔案還是個空殼，今天要加入一些程式碼，載入接下來要用的檔案，才能繼續下一步。

第 1 行：由於這個外掛至少要 PHP 7.1.0 以上版本才能用，所以要避免有使用者載入導至網站出現錯誤。如果使用者的 PHP 版本不符合的話，在管理介面時會提示版本相容性的通知。

第 3 行：限制非 AJAX 請求才載入。因為 AJAX 請求和這個套件沒關係，沒必要在 AJAX 請求時也載入讓記憶體增肥。

第 6 行：引入 Composer 自動載入程式。已經執行過 composer require shieldon/simple-cache 下載要用的 Simple Cache 套件了。

第 8 行：在後台管理介面才載入。因為前端用不到，沒必要在前端也載入讓記憶體增肥。

第 9-11 行：同檔案架構表裡的說明。

第 13 行：主功能還沒開始寫.. 先空著 ^^"。

建立選單入口

（圖：外掛選單入口）

我們要在選單中產生一個如上圖所示的外掛設定入口。程式碼位於 inc/admin/menu.php 這個檔案。

範例：/day-27/cache-master/inc/admin/menu.php

（圖 C：menu.php 程式碼截圖）

第 11 行：將第 18 至第 29 行這個名為 scm_option 的函式掛入 admin_menu 這個 Hook 中。當 WordPress 執行到 admin_menu 時，就會執行將第 18 至第 29 行這一段的程式碼。

第 21 行：add_options_page 這個函式是讓選單入口長出來的關鍵。

add_options_page( 
    string $page_title, // 網頁標題
    string $menu_title, // 選單標題
    string $capability, // 有此權限的使用者才看的到
    string $menu_slug,  // 網址的 slug
    callable $function = '', // 回呼函式
    int $position = null // 5.3.0 才加的屬性。調整位置用。
)

第 26 行：回呼函式的名字。執行 scm_option_page 這個函式。
第 36-55 行：函式 scm_option_page。
呈現「設定頁面」的網頁。裡面很多 HTML 的 code。

第 48 行：settings_fields
產生 input type=hidden 類型的欄位，像是防止 CSRF 攻擊用的 token。

settings_fields(
    string $option_group // 設定的 group ID。
)

第 49 行：do_settings_section
印出設定值的欄位到網頁中。

do_settings_sections(
    string $page // 設定的 page ID。
)

建立設定頁面

要產生完整的設定頁面，必須完成設定欄位的註冊才行。

（圖 D：外掛設定頁面）

程式碼位於 inc/admin/setting.php 這個檔案。

範例：/day-27/cache-master/inc/admin/setting.php

（圖 E：setting.php 程式碼截圖 - 上半部）

第 11 行：將第 18 至第 58 行這個名為 scm_setting 的函式掛入 admin_init 這個 Hook 中。當 WordPress 執行到 admin_init 時，就會執行將第 18 至第 58 行這一段的程式碼。

第 20-22 行：register_setting
這個函式將設定值的欄位註冊。第一個屬性是設定值的 Group ID（同圖 C 第 48 行的說明）。
第二個屬性是選項欄位名稱。

第 20-29 行：add_settings_section
在設定頁面中新增一個設定區塊。

add_settings_section(
    string $id, // 區塊的 ID
    string $title, // 區塊的標題
    callable $callback,　// 回呼函式
    string $page　// 頁面的 ID。(同 圖 C 第 49 行的說明。)
)

第 31-54 行：add_settings_field
在區塊中中新增一個設定欄位。

add_settings_field(
    string $id, // 欄位的 ID
    string $title, // 欄位的標題
    callable $callback, // 回呼函式
    string $page, // 設定頁面的 ID (同 圖 C 第 49 行的說明。)
    string $section = 'default', // 區塊的 ID
    array $args = array() // 額外的傳入屬性
)

第 56 行 是 add_settings_section 的回呼函式，是輸出任何文字用。也可以輸出 HTML。會出現在區塊前面。因為不想輸出，所以輸出空值。

範例：/day-27/cache-master/inc/admin/setting.php

（圖 F：setting.php 程式碼截圖 - 下半部）

第 6-37 行：scm_cb_driver 函式是輸出欄位 HTML 的回呼函式。(圖 E 第 34 行)
第 44-54 行：scm_cb_ttl 函式是輸出欄位 HTML 的回呼函式。(圖 E 第 42 行)
第 61-82 行：scm_cb_uninstall_option 函式是輸出欄位 HTML 的回呼函式。(圖 E 第 50 行)

總結

整個實作後的成果看起來會像下面這張 GIF 示範圖：

流程說明：

• 第一個頁面展示的是筆者在 Day 25 建立的初始化檔案，讓 WordPress 管理介面的外掛列表長出了一個 Cache Master 的項目，接著啟用它。
• 在 Settings 下方，依照今天的步驟「建立選單入口」，建立了一個項目名為 Cache Master 的選單入口連結。
• 最後，依照今天的步驟「建立設定頁面」，建立了這支外掛的設定頁面。

看起來是不是很簡單，一點都不複雜。但實際上還是要自己動手去做過一支外掛才會瞭解整個流程哦！

範例原始碼

• 本篇原始碼 (Day 27 原始碼)
• 鐵人賽用示範外掛儲存庫 (隨時會更新，會和本篇不一樣。)

接著明天要介紹的是在 WordPress 中很重要的觀念，Hook ，只有瞭解了它，才會知道在設計外掛時，要做什麼樣的功能時，該怎麼下手。

鐵人賽終於剩最後三天了，我們明天見。