CodeLog

WordPressのapply_filters、do_action、add_filter、add_actionの使い方とか違いとか

2019-10-06 WordPress

WordPressでHook(Filter)を使う際に、以下の4つの関数が用意されている。

  • apply_filters
  • do-action
  • add_filter
  • add_action

今回は、これら4つの関数の使い方や違いを紹介していく。

Hookとは何か?

そもそも、add_filterとかで使われているHookとは何なのか?

Hookとは、フレームワークやライブラリ、WordPress本体(テーマではなく、wp-includesとか)のソースコードを直接いじることなく、コードを改造できるようにした仕組みの事を言う。

例えば、WordPressでは投稿記事を表示するのにthe_content()(WordPress/post-template.php at master · WordPress/WordPress)の関数を使う。

もし、the_content()の挙動を変えたいと思った時に直接the_content()のコードをいじると、後で「やっぱり元に戻したい」と思ったり、他のプログラマがコードをいじるようになった場合に、すごく扱いにくいコードになってしまう。

そこでadd_filter('the_content', "hoo_func')のようにしてhoo_funcをHookに加えることによって、the_content()を直接いじることなく挙動を変更できる、というメリットがある。

add_actionとadd_filterの使い方とか違い

まずHookを追加するのに使うadd_actionadd_filterだが、これらの関数は全く同じ関数となっている。

特定のアクションに関数をフックします。
この関数は add_filter() のエイリアスです。
アクションフックの一覧についてはアクションフック一覧をご覧ください。アクションは(通常は)WordPress コアが do_action() を呼び出すときにトリガーされます。
関数リファレンス/add action - WordPress Codex 日本語版

実際にadd_actionのコードを見ていると、単にadd_filterをしているだけだと分かる。

<pre class="wp-block-preformatted code lang-php"><span class="synSpecial"><?php</span>
<span class="synPreProc">function</span> add_action<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span> <span class="synStatement">=</span> <span class="synConstant">10</span>, <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span> <span class="synStatement">=</span> <span class="synConstant">1</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synStatement">return</span> add_filter<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span>, <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span> <span class="synSpecial">)</span>;
<span class="synSpecial">}</span>

参考:WordPress/plugin.php at master · WordPress/WordPress

で、add_filterはなにをしているかと言うと、以下のようなコードになっている。

<pre class="wp-block-preformatted code lang-php"><span class="synSpecial"><?php</span>
<span class="synPreProc">function</span> add_filter<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span> <span class="synStatement">=</span> <span class="synConstant">10</span>, <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span> <span class="synStatement">=</span> <span class="synConstant">1</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synType">global</span> <span class="synStatement">$</span><span class="synIdentifier">wp_filter</span>;
<span class="synStatement">if</span> <span class="synSpecial">(</span> <span class="synStatement">!</span> <span class="synStatement">isset</span><span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">wp_filter</span><span class="synSpecial">[</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span> <span class="synSpecial">]</span> <span class="synSpecial">)</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synStatement">$</span><span class="synIdentifier">wp_filter</span><span class="synSpecial">[</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span> <span class="synSpecial">]</span> <span class="synStatement">=</span> <span class="synPreProc">new</span> WP_Hook<span class="synSpecial">()</span>;
<span class="synSpecial">}</span>
<span class="synStatement">$</span><span class="synIdentifier">wp_filter</span><span class="synSpecial">[</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span> <span class="synSpecial">]</span><span class="synType">-></span>add_filter<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span>, <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span> <span class="synSpecial">)</span>;
<span class="synStatement">return</span> <span class="synConstant">true</span>;
<span class="synSpecial">}</span>

上記のコードを見てわかるように、add_filterではグローバル変数のwp_filtersを使っている。このwp_filtersは連想配列となっており、キーにはadd_filter( $tag, $foo_func, )の第1引数$tagが使われて、Hookを識別するHook名の役割を持つ。

そして、new WP_Hook();でWP_Hookクラスを初期化したものを配列のvalueとして扱う。

参考:WordPress/plugin.php at master · WordPress/WordPress

<pre class="wp-block-preformatted code lang-php"><span class="synSpecial"><?php</span>
<span class="synType">public</span> <span class="synPreProc">function</span> add_filter<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span>, <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synStatement">$</span><span class="synIdentifier">idx</span>              <span class="synStatement">=</span> _wp_filter_build_unique_id<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">tag</span>, <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>, <span class="synStatement">$</span><span class="synIdentifier">priority</span> <span class="synSpecial">)</span>;
<span class="synStatement">$</span><span class="synIdentifier">priority_existed</span> <span class="synStatement">=</span> <span class="synStatement">isset</span><span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>callbacks<span class="synSpecial">[</span> <span class="synStatement">$</span><span class="synIdentifier">priority</span> <span class="synSpecial">]</span> <span class="synSpecial">)</span>;
<span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>callbacks<span class="synSpecial">[</span> <span class="synStatement">$</span><span class="synIdentifier">priority</span> <span class="synSpecial">][</span> <span class="synStatement">$</span><span class="synIdentifier">idx</span> <span class="synSpecial">]</span> <span class="synStatement">=</span> <span class="synType">array</span><span class="synSpecial">(</span>
<span class="synConstant">'function'</span>      <span class="synStatement">=></span> <span class="synStatement">$</span><span class="synIdentifier">function_to_add</span>,
<span class="synConstant">'accepted_args'</span> <span class="synStatement">=></span> <span class="synStatement">$</span><span class="synIdentifier">accepted_args</span>,
<span class="synSpecial">)</span>;
<span class="synComment">// if we're adding a new priority to the list, put them back in sorted order</span>
<span class="synStatement">if</span> <span class="synSpecial">(</span> <span class="synStatement">!</span> <span class="synStatement">$</span><span class="synIdentifier">priority_existed</span> <span class="synStatement">&&</span> <span class="synIdentifier">count</span><span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>callbacks <span class="synSpecial">)</span> <span class="synStatement">></span> <span class="synConstant">1</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synIdentifier">ksort</span><span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>callbacks, SORT_NUMERIC <span class="synSpecial">)</span>;
<span class="synSpecial">}</span>
<span class="synStatement">if</span> <span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>nesting_level <span class="synStatement">></span> <span class="synConstant">0</span> <span class="synSpecial">)</span> <span class="synSpecial">{</span>
<span class="synStatement">$</span><span class="synIdentifier">this</span><span class="synType">-></span>resort_active_iterations<span class="synSpecial">(</span> <span class="synStatement">$</span><span class="synIdentifier">priority</span>, <span class="synStatement">$</span><span class="synIdentifier">priority_existed</span> <span class="synSpecial">)</span>;
<span class="synSpecial">}</span>
<span class="synSpecial">}</span>

参考:WordPress/class-wp-hook.php at master · WordPress/WordPress