WordPress

WordPress hooks filters 解析:外掛怎麼排隊,才不打架?

外掛裝到十幾支的網站,多數人猜遲早會出事,兩支外掛剛好都想在同一個地方動手腳,網站說不定哪天就當機。實際情況卻不是這樣,一個中大型 WordPress 網站同時掛著二、三十支外掛,天天正常運作,彼此的程式碼卻很少真的撞在一起。

能做到這件事的,是 WordPress 核心裡的 hook 機制。它讓外掛與佈景主題把自己的程式碼插進 WordPress 執行流程裡一個個預先留好的插入點,不必碰觸核心檔案本體,也不必知道其他外掛寫了什麼。搞懂 hook 怎麼運作,不只讓你看得懂別人寫的外掛在做什麼,遇到兩支外掛真的衝突時,也知道問題卡在哪個環節、該從哪裡調整。

這套讓外部程式碼安全插隊的機制,取代的是一個更麻煩的舊做法,也就是直接修改 WordPress 核心檔案。

改核心檔案曾經是擴充 WordPress 唯一的辦法

在 hook 出現以前,外掛或佈景主題想改變 WordPress 的行為,唯一的辦法是直接動 wp-includes、wp-admin 裡的核心檔案,或者直接改別的外掛的原始碼。想在文章列表多加一欄,就得找到印出那個列表的核心函式,把想加的程式碼硬塞進去。

這麼做的後果很直接。WordPress 每次核心更新都會整批覆蓋掉這些修改,升級一次,自己動過的地方就得重改一次;多支外掛同時想改同一份檔案,則會互相蓋掉對方的版本,誰的改動留下來全看誰最後存檔。而且這些改動混在核心程式碼裡,想把某個功能解除安裝,也沒有乾淨的方式把它復原。

WordPress 官方的外掛開發手冊把 hook 定義成核心事先埋好的插入點,外掛與佈景主題透過這些點介入 WordPress 的執行流程,不需要動到核心原始檔案本體。換句話說,hook 解決的正是上面那個問題,只要核心先留好插入點,外部程式碼就有地方可以安全掛進去,不用再碰任何一行核心程式碼。

直接改 wp-includes、wp-admin 核心檔案會被更新覆蓋、互相蓋掉;hook 讓外掛與佈景主題掛上核心預留的插入點,不動核心原始檔案
hook 出現前,外掛只能把程式碼硬塞進核心檔案;有了 hook,外掛與佈景主題改從核心預留的插入點掛進執行流程。

Hook 分成執行任務的 Action 與修改資料的 Filter 兩種

WordPress 的 hook 其實只分兩種:Action 與 Filter。差別不在用途細節,而在有沒有回傳值。Action 是在某個時間點執行一段任務,做完就結束,不需要把任何東西交回去;Filter 則是攔截一個即將被使用的值,處理完必須回傳,讓後面的程式碼拿到修改後的結果。

這個「動作」與「資料」的分野,決定了後面所有規則怎麼運作。你只要記住一句話:Action 拿到資訊、做點事、什麼都不回傳;Filter 拿到資訊、改點東西、把改完的結果回傳回去。搞混這兩者最常見的後果,就是在該回傳的地方忘記回傳,或是在不該回傳的地方硬塞一個回傳值。

兩種 hook 各自對應一對函式:Action 用 do_action() 觸發、add_action() 掛勾;Filter 用 apply_filters() 觸發、add_filter() 掛勾。

Action 做完事不回傳,用 do_action() 與 add_action();Filter 修改資料後必須回傳,用 apply_filters() 與 add_filter()
Action 與 Filter 的分野不在用途細節,而在有沒有回傳值:Action 做事,Filter 改資料並交回結果。

Action 執行任務但不回傳任何值

Action 的典型用途,是在某個時機執行一件事,例如文章發布的當下、使用者登入完成之後,或是頁面某個固定位置要輸出東西。WordPress 核心會在這些時間點呼叫 do_action(),任何外掛只要用 add_action() 把自己的函式掛上同一個 hook 名稱,就能在那個時機被連帶執行。

官方文件給的範例只有幾行,示範的正是 hook 名稱與回呼函式的最小配對:

function wporg_callback() {
    // do something
}
add_action( 'init', 'wporg_callback' );Code language: PHP (php)

當 init 這個 hook 被執行時,wporg_callback() 就會被呼叫。官方文件也明確指出,Action 的回呼函式不會把任何東西回傳給呼叫它的 Action hook,它只負責做事,不負責交回結果。

Filter 修改資料,還要負責把結果傳回去

Filter 處理的是資料,常見用途像是修改文章標題、調整要輸出的 HTML 的 class,或是在資料存進資料庫前先做點加工。用 Filter 要守住一條鐵則,拿到什麼,就要把處理完的結果回傳什麼,忘了回傳,資料就在半路弄丟了。

官方範例用 the_title 這個過濾器示範:

function wporg_filter_title( $title ) {
    return 'The ' . $title . ' was filtered';
}
add_filter( 'the_title', 'wporg_filter_title' );Code language: PHP (php)

wporg_filter_title() 拿到原本的標題 $title,加工後回傳新的字串,WordPress 才會用這個新字串取代原本要輸出的標題。官方文件也提醒,Filter 應該保持單純,只負責處理傳進來的那個值,不應該去動全域變數,也不應該順便輸出任何內容,它的責任範圍就是改資料、回傳資料,不多做別的事。

回呼函式寫好後,交給 add_action 或 add_filter 註冊

要把一段程式碼掛上 hook,做法固定分兩步:先寫一個普通的 PHP 函式,也就是回呼函式,再用 add_action() 或 add_filter() 把這個函式登記到某個 hook 名稱上。兩支函式的簽名結構相同:

add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 );
add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 );Code language: PHP (php)

前兩個參數是必填,$priority 與 $accepted_args 雖然是選填,卻是後面兩個關鍵問題的答案:同一個 hook 掛了十幾支外掛的函式時誰先誰後,以及為什麼回呼函式有時候收不到該收的參數。

Action 與 Filter 底層其實共用同一套機制。WordPress 原始碼裡,add_action() 的內部實作就是直接呼叫 add_filter():

function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
    return add_filter( $hook_name, $callback, $priority, $accepted_args );
}Code language: PHP (php)

也就是說,不管你掛的是 Action 還是 Filter,WordPress 都把它們存進同一套資料結構裡排隊,差別只在觸發時要不要處理回傳值。

add_action 與 add_filter 共用的四個參數

四個參數各自的角色很單純。$hook_name 是要掛上的 hook 名稱,必填;$callback 是要被呼叫的回呼函式,必填;$priority 決定執行順序,選填,預設值是 10;$accepted_args 決定回呼函式最多能收到幾個參數,選填,預設值是 1。

這四個參數裡,前兩個決定掛在哪裡、掛什麼,後兩個決定什麼時候輪到你、你能拿到多少資訊。多數人寫外掛時只填前兩個,後兩個沿用預設值,大部分情況下也確實夠用;問題是預設值不夠用的時候,往往查不出原因。

accepted_args 沒設對,回呼函式收不到該收的參數

do_action() 或 apply_filters() 觸發時,常常會附帶好幾個參數一起傳出來,但如果掛勾時沒有把 $accepted_args 設成對應的數字,回呼函式預設只會收到 1 個參數,其餘就算觸發端有傳,也不會送進你的函式。

官方文件用 save_post 這個 hook 具體示範這個狀況。WordPress 儲存文章時,核心觸發這個 hook 的寫法相當於:

do_action( 'save_post', $post->ID, $post, $update );Code language: PHP (php)

一次傳出 3 個參數:文章 ID、文章物件、是否為更新。如果只是照預設寫 add_action( 'save_post', 'wpdocs_my_save_post' ),回呼函式就只收得到第一個參數。要多拿幾個參數,就得把第四個參數設成對應的數量,例如想收齊 3 個:

add_action( 'save_post', 'wpdocs_my_save_post', 10, 3 );

function wpdocs_my_save_post( $post_ID, $post, $update ) {
    // do stuff here
}Code language: PHP (php)

$accepted_args 設成 3,函式才會宣告成收 3 個參數、正確拿到 $post_ID、$post、$update。官方文件也補充,如果 apply_filters() 呼叫傳出 4 個參數,掛上的回呼函式可以選擇接受 0 到 4 個,只要沒有指定 $accepted_args,一律視為只接受 1 個。這個限制不會噴出任何錯誤訊息,函式就是安靜地少拿到幾個參數,很容易讓人除錯老半天,才發現問題出在這一個沒設對的參數上。

save_post 觸發時傳出 3 個參數,沒設 $accepted_args 只收到第 1 個,設成 3 才拿得到 $post_ID、$post、$update
$accepted_args 沒設對不會報錯,回呼函式只是安靜地少拿到參數;save_post 要設成 3 才收得齊。

十幾支外掛掛在同一個 hook 上,執行順序由 priority 排定

同一個 hook,例如 init、wp_head,可以被無數支外掛同時掛上回呼函式,WordPress 不會因此出錯或衝突。原因是每一個 hook 背後其實有一份依 priority 排好的隊伍,所有掛上來的函式依序輪流執行,只是排隊的先後不同而已。

官方文件給了一個完整範例,示範四支回呼函式的排序邏輯:

add_action( 'init', 'wporg_callback_run_me_late', 11 );
add_action( 'init', 'wporg_callback_run_me_normal' );
add_action( 'init', 'wporg_callback_run_me_early', 9 );
add_action( 'init', 'wporg_callback_run_me_later', 11 );Code language: PHP (php)

實際執行順序跟程式碼寫的先後無關,只看 priority:先跑 priority 9 的 wporg_callback_run_me_early(),接著是沒設 priority、預設值 10 的 wporg_callback_run_me_normal(),再來是 priority 11 的 wporg_callback_run_me_late(),最後才輪到同樣是 priority 11、但是後掛上去的 wporg_callback_run_me_later()。官方文件也列出幾個關鍵事實:priority 是正整數,一般落在 1 到 20 之間,理論上沒有上限,但實務上的上限大約是 100;預設值是 10。

四支掛在 init 的回呼函式依 priority 9、10、11、11 執行,同為 11 時先掛上的先跑,跟程式碼先後無關
執行順序只看 priority,數字小的先跑;priority 相同時,依掛上去的先後排隊。

數字小的 priority 比數字大的先執行

排序規則濃縮成一句話就是,數字小的先跑,數字大的後跑。官方文件對 $priority 這個參數的描述很直白,數字愈小,執行得愈早。

這也解釋了為什麼預設值訂在 10,而不是 1 或 100:訂在中間值,才留得出空間讓某支外掛想搶先執行時往小的數字調,想排在最後執行時往大的數字調。很多外掛不會特別改這個參數,直接沿用預設值 10,結果同一個 hook 上常有一大串函式擠在同一個優先度裡。

同一個 priority 依註冊順序排隊執行

當多支外掛都用預設 priority 10,沒有特別指定時,誰先誰後不是隨機決定,而是依誰的程式碼先被 WordPress 載入、先呼叫 add_action() 來決定。官方文件寫得很明確,同一個 priority 底下的函式,依照它們被加進這個 action 的順序執行。

外掛的載入順序,通常又跟隨外掛資料夾名稱的字母順序這類外掛自己控制不了的因素。也就是說,同優先度的執行順序其實不完全操之在單一外掛手上,真的在意順序時,不能只依賴預設值,得自己動手把 priority 調開。

Filter 像接力棒,每個外掛拿到的都是前一棒修改過的值

Filter 專屬的一個行為,是十幾支外掛裝在一起卻不會打架的第二個關鍵機制。同一個 filter hook 如果被十幾支外掛同時掛了回呼函式,這些函式不是各自拿到同一份原始資料、各改各的、最後互相覆蓋,而是依 priority 順序接力:第一個函式先拿到原始值,處理完回傳;第二個函式拿到的已經是第一個函式改過的結果,再處理、再回傳,依此類推,直到全部跑完,才把最終結果交給呼叫端使用。

官方文件在 add_filter() 的說明裡描述得很清楚,filter 被套用時,每一個綁定的回呼函式都依 priority 順序執行,並且有機會透過回傳一個新的值來修改資料。

官方〈自訂 hook〉頁面的範例,示範了這個接力實際怎麼發生。假設某支外掛註冊文章類型時,先讓參數陣列經過一個 filter,再交給 register_post_type():

register_post_type(
    'post_type_slug',
    apply_filters( 'wporg_post_type_params', $post_type_params )
);Code language: PHP (php)

另一支外掛掛上這個 filter,把其中一個設定值改掉再回傳:

add_filter( 'wporg_post_type_params', 'myprefix_change_post_type_params' );

function myprefix_change_post_type_params( $post_type_params ) {
    $post_type_params['hierarchical'] = true;
    return $post_type_params;
}Code language: PHP (php)

如果同時有第三支外掛也掛了同一個 filter,它拿到的 $post_type_params 就已經是上一支外掛改過的版本,不是最原始那一份。這正是為什麼十幾支外掛可以疊加修改同一個字串或陣列,卻不會互相打架,因為規則早就講好,每一棒都要把資料完整交給下一棒。

沒回傳值的 filter 會讓後面外掛收到空值

接力規則的反面,就是漏寫 return 會發生的事。PHP 函式沒有明確回傳值時,預設就是 null,這個 null 會被當成這一棒交出的結果,繼續往下傳。後面排隊的外掛與最終呼叫端拿到的,都會是這個空值,資料等於在半路就不見了。

Filter 依 priority 接力傳值,每一棒拿到前一棒回傳的結果;中間一棒漏寫 return,後面外掛與呼叫端都拿到 null
Filter 的每一棒都要把資料完整回傳給下一棒,漏寫 return 就會把 null 一路往下傳,輸出變一片空白。

這是初學者寫 Filter 最常犯、也最難自己發現的錯誤。函式本身沒有語法錯誤,執行也不會噴出任何警告,問題只會反映在最後輸出的地方變成一片空白,或是某個原本該有值的欄位莫名消失。回頭檢查時,先確認每一個掛上 Filter 的回呼函式最後一行是不是都有 return,通常就能找到問題出在哪一支外掛。

多支外掛搶著在同一個時機動作,是打架最常見的成因

前面幾節解釋的都是為什麼平常不會打架,但外掛之間真正會撞在一起,原因並不是 hook 機制本身有問題,而是多支外掛剛好想在同一個時間點做互斥的事,例如都想輸出同一段標籤,或是都想覆蓋同一個設定值。這時候誰先誰後,就直接決定了最後的結果對不對。

官方〈自訂 hook〉頁面對命名衝突的說明,也從側面佐證了這一點,當兩個開發者用同一個 hook 名稱處理完全不同的用途時,就會出現難以排查的錯誤。換句話說,衝突的根源在於「共用同一個掛勾點」這件事本身,不是 priority 排序機制設計得不好。這套機制原本就預期會有很多支程式碼掛在同一個地方,只是沒辦法保證那些程式碼彼此想做的事不會互相牴觸。

wp_head 與 plugins_loaded 是最容易被搶著佔用的熱門 hook

WordPress 核心裡,有兩個時機點特別容易被大量外掛同時盯上。一個是 wp_head,也就是頁面 <head> 區段裡、</head> 結束之前的那個時間點,SEO、統計追蹤類的外掛常常在這裡插入自己的標籤或程式碼片段;另一個是 plugins_loaded,所有外掛載入完畢後才會觸發,很多外掛拿它當作初始化的起點。

這兩個 hook 之所以熱門並不是巧合,而是它們各自對應到外掛最常見的兩種需求,一個管頁首要輸出什麼,一個管載入完成後該做什麼準備工作。正因為太多外掛同時盯著同一個時機,順序稍微跟預期不同,就特別容易讓某個功能看起來跑掉了,其實只是排隊的位置跟你想的不一樣。

remove_action 換掉別人掛的回呼函式,callback、priority 與時機都要對上

真的想調整別人排好的隊伍時,可以用 remove_action()(Filter 對應的是 remove_filter())把某個已經掛上去的回呼函式從 hook 上拿掉,通常用在想取消某個預設行為、換成自己的版本。函式簽名是:

remove_action( $hook_name, $callback, $priority = 10 );Code language: PHP (php)

有一個關鍵限制最容易被忽略,要移除的 $callback 與 $priority,必須跟當初掛上去時完全一致。官方文件寫得很清楚,移除失敗不會給任何警告。如果原本用 priority 20 掛上去,你卻用預設值 10 去移除,remove_action() 會安靜地什麼都不做,原本那個回呼函式照樣執行,你可能完全不知道自己的移除指令根本沒生效。

另一個容易忽略的前提是時機。remove_action() 得等對方的 add_action() 先執行過才能呼叫,才移除得掉;如果你的移除程式碼比對方掛勾的程式碼先跑,那個時間點 hook 上根本還沒有那個回呼函式可以移除,一樣不會有任何提示,指令就這麼失效了。這也是為什麼常常得把移除動作往後掛到更晚的時機點,才能確保對方已經掛上去了。

remove_action 的 callback 與 priority 要跟掛上時一致,且要在對方 add_action() 之後呼叫,否則會無聲失效
remove_action 移除失敗不會給任何警告,callback、priority、時機三個條件都對上,才移除得掉。

官方原始碼也顯示,remove_action() 內部直接呼叫 remove_filter(),跟 add_action() 呼叫 add_filter() 是同一套設計邏輯,移除的規則自然也跟掛上去的規則對稱。

自訂 hook 讓其他外掛也能安插進自己的功能

前面幾節都在講使用核心提供的 hook,但自訂 hook 要處理的是另一半的功能,外掛自己也能開放 hook 給別人用。任何外掛都可以在自己程式碼的關鍵位置呼叫 do_action() 或 apply_filters(),開放一個屬於自己的插入點,讓其他外掛透過 add_action()、add_filter() 掛進來擴充或修改它的行為,做法跟使用核心 hook 完全一樣。

十幾支外掛能疊在一起互相擴充,而不是各自獨立運作、互不相干,靠的正是這另一半機制。官方文件說得很直接,建立自訂 hook,Action 用 do_action(),Filter 用 apply_filters();要把回呼函式掛上自訂 hook,一樣是 Action 用 add_action(),Filter 用 add_filter()。

官方給的範例是這樣的,某支外掛在自己的設定頁模板裡放一段程式碼,開放一個插入點:

do_action( 'wporg_after_settings_page_html' );Code language: PHP (php)

另一支外掛就能掛上這個 hook,插入自己的設定欄位:

add_action( 'wporg_after_settings_page_html', 'myprefix_add_settings' );Code language: PHP (php)

四個函式在自訂情境下的角色分工,跟使用核心 hook 時完全對稱,先開放插入點的一方負責呼叫 do_action() 或 apply_filters(),想插隊進來的一方則負責呼叫 add_action() 或 add_filter()。

外掛用 do_action() 或 apply_filters() 開放自訂 hook,其他外掛用 add_action() 或 add_filter() 掛上同一個 hook 名稱
自訂 hook 的分工跟使用核心 hook 對稱:開放插入點的一方觸發,想插隊的一方掛勾。

前綴命名避免不同外掛的 hook 撞號

自訂 hook 名稱如果取得太通用,例如直接叫 email_body,很容易跟別的外掛不小心用了同一個名稱做完全不同的事,變成難以排查的隱性衝突。官方文件舉的正是這個例子:一個叫 email_body 的 filter,通用到兩個以上的開發者都可能在不同外掛裡拿它做完全不同的用途。

解法很單純,幫自己的 hook 名稱加上一個獨一無二的前綴,公司名、外掛名、開發者代稱都可以,跟外掛函式命名要加前綴是同一個道理。官方文件自己示範用的前綴是 wporg_,前綴愈獨特,愈不會跟其他外掛的命名空間打架。

下次打開一支外掛的原始碼,看到滿滿的 add_action()、add_filter(),那不是隨手加上去的裝飾,而是每一行都在跟 WordPress 登記自己要排進哪個隊伍、什麼時候被叫到。真正會讓兩支外掛打起來的,從來不是這套排隊機制,而是兩支外掛剛好想在同一個時間點做同一件事,這種情況多半靠拉開 priority 就能解決,不必去改任何一支外掛的原始碼。

常見問答

本區問答由 AI 依文章內容自動整理,僅供快速參考,正式內容仍以全文為準。

Action 與 Filter hook 差在哪?

WordPress 的 Action 與 Filter 差在有沒有回傳值。Action 在某個時間點執行一段任務、做完就結束,不回傳任何東西;Filter 攔截一個即將被使用的值,處理完必須回傳,讓後面的程式碼拿到修改後的結果。

WordPress 多支外掛怎麼決定執行順序?

WordPress 靠 priority 參數排定同一個 hook 上回呼函式的執行順序,數字小的先跑、數字大的後跑,預設值是 10。priority 相同時,依回呼函式被加進這個 hook 的先後順序執行。

add_action 的回呼函式為什麼收不到參數?

add_action 的回呼函式收不到參數,多半是 $accepted_args 沒設對。沒有指定時,回呼函式預設只收得到 1 個參數,其餘就算觸發端有傳也不會送進來,而且不會出現任何錯誤訊息。

Filter 忘了寫 return 會怎樣?

WordPress Filter 的回呼函式漏寫 return 時,PHP 預設回傳 null,這個空值會被當成這一棒的結果往下傳,後面的外掛與最終呼叫端都只拿到空值。函式不會噴出任何警告,問題只會在輸出的地方變成一片空白。

remove_action 為什麼移除不掉別人的函式?

remove_action 移除不掉,通常是 callback 或 priority 跟當初掛上去時不一致,或是移除時對方的 add_action 還沒執行。兩種情況都不會出現任何警告,所以常要把移除動作往後掛到更晚的時機點。

資料來源
  1. Plugin Handbook - Introduction to Plugin Development — WordPress官方外掛開發手冊
  2. Plugin Handbook - Hooks — WordPress官方外掛開發手冊
  3. Plugin Handbook - Hooks: Actions — WordPress官方外掛開發手冊
  4. Plugin Handbook - Hooks: Filters — WordPress官方外掛開發手冊
  5. Plugin Handbook - Hooks: Custom Hooks — WordPress官方外掛開發手冊
  6. Code Reference - add_action() Function — WordPress Code Reference
  7. Code Reference - add_filter() Function — WordPress Code Reference
  8. Code Reference - save_post Hook — WordPress Code Reference
  9. Code Reference - remove_action() Function — WordPress Code Reference
  10. Code Reference - activate_plugin() Function — WordPress Code Reference