WordPress特集 - アクションフック・フィルターフックの使い方

WordPress では、WordPress が処理を行う途中のタイミングで、何らかの処理を実行する関数を呼び出す仕組みを持っています。この仕組みをアクションフック・フィルターフックと呼びます。他のフレームワークで言うところの、イベントハンドラやイベントリスナに相当します。

【記事執筆時の環境】
WordPress 5.8

アクションフックとフィルターフック

【参考ページ】
Codex 日本語版 - プラグインAPI
Plugin Handbook - Hooks

フックとは、特定のタイミングで何らかの処理を実行するためのイベントトリガーです。フックを使うと、WordPress 本来の処理に変更を加えたり、新たに処理を追加することができます。

WordPress はさまざまなタイミングでフックを用意しています。そしてそれぞれのフックで、あらかじめ関数を登録し処理を実行させています。そのフックに対して、ユーザーは処理する関数を追加できます。また、WordPress が登録している関数の処理をキャンセルすることもできます。

フックには2種類あり、それぞれ「アクションフック」「フィルターフック」と呼んでいます。2つのフックの違いは以下です。

アクションフック

アクションフックでは、何らかの動作をするアクション(関数)がフックされていて、処理を行うため起動します。ユーザーがアクションフックを使うということは、WordPress 標準の処理に追加の処理を差し込む形になります。

なお、ここで言う「アクション」と「フック」の言葉の意味は、さまざま使われていますので注意してください。
「アクション」は、フックする関数の意味でも使われますし、イベントトリガーであるフックの意味として使われることもあります。「フックにアクションを追加する」「アクションに関数を追加する」は同じ意味です。
また「フック」は、アクションフック名として使われますが、関数を追加する意味での「フックする」という動詞でも使われます。

フィルターフック

フィルターフックでは、WordPress は入力に対してどういう内容を出力するかのデータ処理を行っています。ユーザーがフィルターフックを使うということは、WordPress が元々行っているデータ処理の結果を差し替える形になります。具体的には、フックした関数の処理では特定の変数を書き換えることになります。
「アクションフック -> 処理の追加」ということに対して、「フィルターフック -> データの差し替え」になります。

またフィルターフックではアクションフックと違い、フックした関数の戻り値として、書き換えた後の結果を WordPress コアに受け渡す必要があります。

アクションフックの使い方

【参考ページ】
Plugin Handbook - Actions

アクションフック一覧

アクションフックは独自のものを設置することもできますが、一般的には WordPress があらかじめ設置しているアクションフックを利用します。
WordPress が設置しているアクションフックの一覧は、下記ページをご覧ください。
例えば、WordPress が完全に読み込まれた後(wp_loaded)や、管理画面のメニューが読み込まれる前(admin_menu)などがあります。

Codex 日本語版 - プラグインAPI/アクションフック一覧
Codex - Plugin API/Action Reference
WordPress Hooks Database

アクションフックの実行

アクションフックは、関数 do_action() によって実行されます。WordPress が設置しているアクションフックを利用する場合は、この関数を意識する必要はありません。WordPress コアのファイル内のどこかに記述されています。

独自のアクションフックを設置する場合は、下記のようなコードをテンプレート内に記述します。
do_action( 'アクションフック名' ) で、アクションフックの設置と実行が行われます。そしてこのアクションフックに対して、functions.php 内でフックする関数(アクション)を登録すれば処理は実行されます。

フックする関数の登録

functions.php に記述します。
フックする関数の定義をし、関数 add_action() を使ってアクションフック名とフックする関数を指定します。
add_action() の書式は下記になります。

add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 )

【パラメーター】
$hook_name

フックされるアクションフック名。
$callback
アクションフックが呼び出されたときに実行される関数。
$priority
アクションフックに追加されている関数が実行される優先順序を指定します。小さい数値ほど早く実行され、同じ優先順位の場合はアクションフックに追加された順序で実行されます。
初期値:10
$accepted_args
フックした関数が受け入れられる引数の数。
初期値:1

【戻り値】
常に true を返します。

下記はコード例です。ウィジェットの初期化をするアクションフック widgets_init で、ウィジェットエリアを登録する関数を追加しています。

アクションフックに追加されている関数を削除

用意されているアクションフックでは、WordPress はあらかじめいくつかの関数を登録し処理を実行させていますが、remove_action() を使って、その関数を削除し実行を停止することができます。

例えば、テンプレートタグ wp_head() を読み込むと、アクションフック wp_head が実行されますが、そこに追加されている主な関数は以下になります。

これらの関数の中には、Web ページの head 要素内にタグを自動出力しているものがありますが、それらのタグ出力を抑制したい場合もあります。
そこで、WordPress バージョンを出力する wp_generator や、RSS フィード/コメントフィードを出力する feed_links/feed_links_extra を削除するには下記コードを functions.php に記述します。引数は add_action() で追加されたとおりにします。

フィルターフックの使い方

【参考ページ】
Plugin Handbook - Filters

フィルターフック一覧

フィルターフックもアクションフックと同様、一般的には WordPress があらかじめ設置しているフィルターフックを利用します。
WordPress が設置しているフィルターフックの一覧は、下記ページをご覧ください。
例えば、the_title や the_content など、投稿や固定ページの編集画面で入力したデータをフィルターするフックが用意されています。

Codex 日本語版 - プラグインAPI/フィルターフック一覧
Codex - Plugin API/Filter Reference
WordPress Hooks Database

フィルターフックの適用

フィルターフックは、関数 apply_filters() によって適用されます。アクションフックと同様、独自のフィルターフックを設置することもできますが、WordPress が設置しているフィルターフックは、コアファイルのどこかでこの関数を使用し実装されています。

フックする関数の登録

functions.php に記述します。
フックする関数の定義をし、関数 add_filter() を使ってフィルターフック名とフックする関数を指定します。
add_filter() の書式は下記になります。

add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 )

【パラメーター】
$hook_name

フックされるフィルターフック名。
$callback
フィルターフックが呼び出されたときに実行される関数。
$priority
フィルターフックに追加されている関数が実行される優先順序を指定します。小さい数値ほど早く実行され、同じ優先順位の場合はフィルターフックに追加された順序で実行されます。
初期値:10
$accepted_args
フックした関数が受け入れられる引数の数。
初期値:1

【戻り値】
常に true を返します。

コールバック関数では、引数で受け取った変数の内容を変更して返すか、変更後の値を返します。ただし引数と戻り値は同じ型でなければいけません。
引数は apply_filters() でどのようにフィルターフックを実装しているかに依存します。
フィルターフックの実装状況は、Code Reference で確認してください。

Code Reference - Hooks

下記に functions.php に記述するコード例を示します。投稿タイトルを加工するフィルターをかけています。
なお、フィルターフック the_title には $title と $id の2つの引数がありますが、この例では $id は使用しないため省略することも可能です。その場合は add_filter() に指定する引数オプションはデフォルト値の1を適用するため記述しません。

フィルターフックに追加されている関数を削除

remove_filter() を使って、追加されている関数を削除し実行を停止することができます。

下記は、フィルターフック the_content からテキストを自動整形する関数 wpautop() を削除するコードです。

falseを返す関数

フィルターフックに false を返すと、そのフィルターを無効にできます。
WordPress には false を返す関数 __return_false() が定義されています。
例えば、WordPress では本文内に入力されたテキストの一部を自動的に変換する機能があるのですが、その機能を停止するにはフィルターフック run_wptexturize に false を返します。
下記コードを functions.php に記述します。

ちなみに false を返す関数の他にも、true を返す関数や空の文字列を返す関数など全部で6種類が定義されています。
__return_true
__return_false
__return_zero
__return_empty_array
__return_null
__return_empty_string

例として、WordPress のすべての自動更新を無効にするには、下記コードを記述します。

«次の特集記事»
«前の特集記事»

スポンサーリンク

WordPress 特集記事

WordPressの概要

WordPressの仕組み

WordPressのカスタマイズ性

制作環境とインストール

基本設定項目

追加設定項目

Gutenbergエディター

具体的な制作作業

応用・高度機能

実践的なTips

よく使われるテーマ紹介

有用なプラグイン紹介

独自テーマによる制作

オンライン講座

Webの基礎マスター講座ページへのリンク


連載講座:WordPressで作る簡単Webサイトページへのリンク

提供しているサービス

WordPressサイト制作出張講座ページへのリンク

WordPress を利用した Webサイト制作の方法を、
あなたのオフィスにうかがいご説明いたします。
料金:¥28,000

サービス詳細ページ >>

申し込みフォーム >>


Webサイト1日公開サービスページへのリンク

一刻も早く Webサイトが必要な方のために、
一緒に作業し1日で公開までもっていきます。
料金:¥28,000

サービス詳細ページ >>

申し込みフォーム >>

スポンサーリンク

ページの先頭へ