您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

WordPress 過濾器機制深度解析：apply_filters 與 add_filter 核心函數詳解

編輯：PHP 相關知識

WordPress 過濾器機制核心概念

WordPress 的插件架構建立在「鉤子」機制之上，其中過濾器負責資料的修改與轉換。掌握 apply_filters() 與 add_filter() 這兩個核心函數，是開發高品質主題與外掛的關鍵。

apply_filters()：建立過濾點

apply_filters() 用於在程式碼中建立一個「過濾點」，讓其他程式碼有機會修改特定的值。它是 WordPress 可擴充性的基石。

函數語法

apply_filters( string $tag, mixed $value, mixed ...$args ): mixed

參數說明

$tag（字串，必填）：過濾器名稱，作為唯一識別碼。
$value（混合，必填）：待過濾的初始值。若無任何函數掛載，將直接返回此值。
$args（混合，選填）：額外傳遞給掛載函數的參數，可無限個。

回傳值

經過所有掛載函數處理後的最終值；若無函數掛載，則回傳原始 $value。

實戰範例

基本用法：無函數掛載時

echo apply_filters( 'custom_text', '預設文字' );

輸出：預設文字

單一函數修改數值

function modify_text() {
    return '已修改的文字';
}
add_filter( 'custom_text', 'modify_text' );
echo apply_filters( 'custom_text', '預設文字' );

輸出：已修改的文字

多函數串聯處理（管道模式）

function append_suffix_1( $text ) {
    return $text . ' - 第一階段';
}
function append_suffix_2( $text ) {
    return $text . ' - 第二階段';
}
add_filter( 'custom_text', 'append_suffix_1' );
add_filter( 'custom_text', 'append_suffix_2' );
echo apply_filters( 'custom_text', '原始值' );

輸出：原始值 - 第一階段 - 第二階段

傳遞額外參數輔助決策

function format_price( $price, $currency, $decimals ) {
    return $currency . number_format( $price, $decimals );
}
add_filter( 'product_price', 'format_price', 10, 3 );
echo apply_filters( 'product_price', 1234.56, 'NT$', 0 );

輸出：NT$1,235

add_filter()：掛載處理函數

add_filter() 將自訂函數掛載到指定的過濾器上，構成「發布-訂閱」模式。

函數語法

add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 ): bool

參數詳解

$tag：目標過濾器名稱，需與 apply_filters() 的 $tag 完全一致。
$function_to_add：回呼函數，接受至少一個參數（被過濾的值），必須返回處理後的值。
$priority：執行優先序，數值越小越早執行，預設 10。相同優先序按掛載順序執行。
$accepted_args：回呼函數接受的參數數量，預設 1。需與 apply_filters() 傳遞的參數數量對應。

回傳值

永遠返回 true。

進階範例：優先序控制

add_filter( 'content_filter', 'func_a', 5 );  // 最早執行
add_filter( 'content_filter', 'func_b', 10 ); // 預設優先序
add_filter( 'content_filter', 'func_c', 15 ); // 最後執行