フック(アクション・フィルター)の記事一覧|WordPressの専門家が作る教科書 https://wordpress.ks-product.com WordPressを活用したウェブサイトの制作方法を教えます Sat, 07 Nov 2026 23:00:00 +0000 ja hourly 1 https://wordpress.org/?v=7.1.5 add_action の引数が受け取れない|accepted_args と Too few arguments https://wordpress.ks-product.com/3085/ Wed, 11 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3085 結論

フックに登録するときの 第4引数 $accepted_args(既定値は 1) が、コールバックに渡される引数の数を決めます。2つ目以降の引数を使いたいなら、使う数を指定します。

add_action( 'save_post', 'my_save', 10, 3 ); // $post_id, $post, $update

省略すると、コールバックには第1引数しか渡されません。引数が2つ以上必須のコールバックでは ArgumentCountError(Too few arguments)になります。引数にデフォルト値があれば、エラーにならずデフォルト値が使われるため、気付きにくい不具合になります。

原因・仕組み

add_action() と add_filter() は同じ仕組みで、登録時の $accepted_args を記録します。フックが実行されると、WordPress は渡された引数のうち先頭からその数だけをコールバックに渡します。公式リファレンスにも、引数の数はフックを実行している do_action() / apply_filters() のソースで確認する、と書かれています。

多く指定してもエラーにはなりません。渡す引数が足りなければ、ある分だけが渡されます。

手順(サンプルコード)

1. 2つ以上受け取るフィルター

// 悪い例:accepted_args を省略
add_filter( 'demo_f', function ( $value, $post_id ) {
    return "$value/$post_id";
} );
// → apply_filters( 'demo_f', 'v', 5 ) で ArgumentCountError

// 良い例
add_filter( 'demo_g', function ( $value, $post_id ) {
    return "$value/$post_id";
}, 10, 2 );

2. コアのフックの引数を調べて指定する

add_action( 'save_post', function ( $post_id, $post, $update ) {
    if ( wp_is_post_revision( $post_id ) ) {
        return;
    }
    // $update が false なら新規作成
}, 10, 3 );

the_title のように、コアが apply_filters( 'the_title', $title, $post_id ) と2つ渡すフックは、10, 2 と書けば投稿IDも受け取れます。

3. 引数の数を確認する

add_action( 'demo_a', function () { echo 'argc=' . func_num_args(); }, 10, 3 );
do_action( 'demo_a', 1, 2, 3 );

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • 省略した2引数のコールバック:ArgumentCountError: Too few arguments to function {closure}(), 1 passed in ...class-wp-hook.php ... and exactly 2 expected。
  • 10, 2 を指定:string(3) "v/5"。
  • 10, 3 で3つ渡した:argc=3。
  • 実際の引数より大きい 10, 5 を指定し、デフォルト値付き引数のコールバック:string(9) "v/default"(エラーにならない)。
  • save_post を 10, 3 で登録して wp_insert_post を実行:$post はオブジェクト、$update=false。
  • the_title を 10, 2 で登録:T#100(投稿IDを受け取れた)。

検証で作成した下書き投稿は削除済みです。ログは testsadd-action-accepted-args-too-few-arguments.md にあります。

add_action の引数が受け取れないときの注意点

  • フィルターで変更できるのは第1引数($value)だけです。他の引数は文脈の情報で、書き換えても元に戻りません(公式リファレンスの記載)。
  • 引数の数は、コアのバージョンで増えることがあります。リファレンスで最新を確認します。
  • クラスメソッドでも同じです。add_action( 'save_post', array( $this, 'save' ), 10, 3 ) のように指定します。

add_action の引数が受け取れないときによくあるミス

  • save_post で $post を使うのに、第4引数を指定しない。
  • accepted_args を実際より少なく書き、後ろの引数が NULL や未定義になる。
  • フックの引数の順番を、記憶で書いて間違える。
  • remove_action で、accepted_args まで一致させようとする(削除に必要なのは優先度までです。remove_action() の使い方|説明・引数・注意点参照)。

add_action の引数が受け取れないときのチェックリスト

  • フックの引数の数と順番を公式リファレンスで確認したか
  • コールバックの引数の数と第4引数が一致しているか
  • 投稿保存系は、リビジョンや自動保存への対策をしたか
  • クラスメソッドでも同じ指定をしているか
  • エラーログで ArgumentCountError が出ていないか

add_action の引数が受け取れないときのFAQ(よくある質問)

Q. 引数が多すぎる指定でも動きますか?
A. 動きます。渡された分だけが渡されます。ただし意図が伝わらないため、必要な数にします。

Q. 引数が0個のコールバックは?
A. 既定(1)のままでも動きます。PHP のユーザー定義関数は、余分に渡された引数を無視するためです。accepted_args に 0 を指定すると、引数なしで呼ばれます(検証環境で func_num_args() が 0 になることを確認)。

Q. 引数の数をプログラムで調べられますか?
A. func_num_args() で、コールバック内で確認できます。

筆者の見解(add_action の引数が受け取れない)

「フックの引数はコアのソースの do_action 行で確認する」というのが、いちばん確実だと考えます。ドキュメントを読むときも、第4引数を先に決めてからコールバックを書くと、型や順番の間違いにも気付きやすいと思います。

add_action の引数が受け取れないときの関連項目

出典(一次情報)

]]>
add_filter で return を忘れると|空表示・NULL の原因と対処 https://wordpress.ks-product.com/3084/ Mon, 09 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3084 結論

フィルターのコールバックは、必ず値を return します。return を忘れると、PHP の関数は NULL を返すため、その値が次の処理へ渡り、タイトルや本文が空になったり、後続のコアの関数が警告を出したりします。条件分岐の中だけに return を書いた場合も、条件に合わなかったときは NULL です。

対処は次の3点です。

  • どの経路でも最後に return $value; する
  • 条件に合わないときは、受け取った値をそのまま返す
  • エラーログと var_dump( apply_filters(...) ) で、戻り値を確認する

原因・仕組み

apply_filters() は、登録されたコールバックの戻り値を次のコールバックの入力に使います。公式の add_filter() リファレンスにも、コールバックは受け取った値を変更して返すもの、と明記されています。add_filter() 自体は、コールバックが何を返すかを検査しません(戻り値は常に true)。

そのため、return のないコールバックを登録しても、エラーにならず、「値が消える」という症状だけが出ます。アクションは戻り値を使わないので、アクションの感覚でフィルターを書くと起きやすいミスです。

手順(サンプルコード)

1. 悪い例(そのまま使わない)

// 悪い例1:return がない
add_filter( 'demo_title', function ( $title ) {
    $title = $title . ' [x]';
} );

// 悪い例2:条件に合わないときの return がない
add_filter( 'demo_title', function ( $title ) {
    if ( $title === 'Hello' ) {
        return $title . ' [x]';
    }
} );

2. 良い例

add_filter( 'demo_title', function ( $title ) {
    return $title === 'Hello' ? $title . ' [x]' : $title;
} );

3. 複数の経路がある場合

add_filter( 'the_content', function ( $content ) {
    if ( ! is_singular( 'post' ) ) {
        return $content;      // 早期リターンでも値を返す
    }
    return $content . '<p>footer</p>';
} );

早期リターンを使うと、最後の return を忘れにくくなります。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • 悪い例1:apply_filters( 'demo_title', 'Hello' ) は NULL。
  • 悪い例2:'Other' を渡すと NULL('Hello' のときだけ値が返る)。
  • 良い例:'Other' は string(5) "Other"、'Hello' は string(9) "Hello [x]"。
  • 配列を受け取って $v[] = 1; だけして return しないと、結果は NULL(配列が消える)。
  • the_content に return のないフィルターを足すと、後続のコアのフィルターが str_replace(): Passing null to parameter #3 ($subject) ... is deprecated を出力し、結果は空文字 "" になった(優先度 1 で登録した再検証では、do_blocks 側のブロックパーサーが preg_match() などで同様の deprecated を出した。警告を出す関数は登録した優先度で変わる)。

ログは testsadd-filter-return-forgotten-null.md に保存しています。

add_filter で return を忘れたときの注意点

  • WP_DEBUG を有効にした開発環境でないと、deprecated などの警告に気付かないことがあります。
  • 型宣言(: string)を戻り値に付けると、return 忘れが TypeError として早く見つかります。ただし、他のプラグインが別の型を渡す場合に備え、型の扱いは慎重に決めます。
  • 引数を2つ以上受け取る場合は、add_filter の第4引数も必要です(add_filter() の使い方|説明・引数・注意点参照)。

add_filter で return を忘れたときによくあるミス

  • 画面に echo して確認するだけで、return を書かない。
  • if の中にだけ return を書く。
  • foreach の中で return して、1件目で終了してしまう。
  • アクションとフィルターの書き方を混ぜる(add_action で書くと戻り値が使われない)。

add_filter で return を忘れたときのチェックリスト

  • すべての分岐の最後に return があるか
  • 条件外のとき、受け取った値を返しているか
  • 返す値の型が、フィルターの想定と合っているか
  • WP_DEBUG で警告を確認したか
  • apply_filters の結果を var_dump で確認したか

add_filter で return を忘れたときのFAQ(よくある質問)

Q. 画面が真っ白になる原因ですか?
A. 本文などが空になる原因にはなります。真っ白(致命的エラー)は、型宣言違反など別の原因を疑ってください。

Q. 戻り値が不要なら、アクションで書いてよいですか?
A. 値を変更しないのであれば、アクションの方が適切です。

Q. どのコールバックが NULL を返したか調べるには?
A. 優先度ごとに apply_filters の途中結果を記録するか、登録されているコールバックを $wp_filter['hook'] で確認します。

筆者の見解(add_filter で return を忘れると)

フィルターは「受け取って、返す」だけの関数と考えるのが、いちばん事故が少ないと思います。書き始めにまず return $value; を先に書いてから、中身を足していくと、書き忘れが減ります。型宣言も、自分のコードの中では積極的に使いたいと考えます。

add_filter で return を忘れたときの関連項目

出典(一次情報)

]]>
独自フックの作り方|do_action と apply_filters の使い分け https://wordpress.ks-product.com/3083/ Sat, 07 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3083 結論

独自フックは、事前の登録なしに do_action()(アクション)または apply_filters()(フィルター)を書くだけで作れます。使い分けは次のとおりです。

  • 出力や処理を差し込ませたい → do_action( 'myplugin_before_card', $id )
  • 値を書き換えさせたい → $html = apply_filters( 'myplugin_card_html', $html, $id )

フック名には、テーマやプラグイン固有の接頭辞を付けます(公式リファレンスでも、プラグインやテーマの slug を前に付ける命名が推奨されています)。引数は、使う側が判断するための材料(投稿IDなど)を渡します。

原因・仕組み

do_action() と apply_filters() は、指定した名前に登録されたコールバックを順に実行するだけの関数です。コールバックが1つもなくてもエラーにならず、apply_filters() は渡した値をそのまま返します。この「何も登録されていなければ素通り」という性質が、拡張ポイントを後から安全に増やせる理由です。

違いは戻り値の扱いです。アクションは戻り値を使わない(do_action は何も返さない)のに対し、フィルターは各コールバックの戻り値が次へ渡され、最終的な値が apply_filters() の戻り値になります。

手順(サンプルコード)

1. 提供側:フックを置く

function mytheme_render_card( $post_id, $title ) {
    do_action( 'mytheme_before_card', $post_id, $title );

    $html = '<div class="card">' . esc_html( $title ) . '</div>';
    $html = apply_filters( 'mytheme_card_html', $html, $post_id );
    echo wp_kses_post( $html ); // フィルターで差し替えられたHTMLも、出力直前に許可タグだけに絞る

    do_action( 'mytheme_after_card', $post_id );
}

デフォルト値を返す設定値も、フィルターで作れます。

function mytheme_per_page() {
    return (int) apply_filters( 'mytheme_per_page', 10 );
}

2. 利用側:フックに処理を登録する

add_action( 'mytheme_before_card', function ( $id, $title ) {
    echo '[before id=' . (int) $id . ']';
}, 10, 2 ); // 引数を2つ受け取るので、第4引数に2

add_filter( 'mytheme_card_html', function ( $html, $id ) {
    return str_replace( 'card', 'card card--' . (int) $id, $html );
}, 10, 2 );

3. 配列・参照を渡す

配列を1つ渡すのは通常の do_action( 'x', $array ) で足ります。参照渡しにしたい場合は do_action_ref_array( 'x', array( &$obj ) ) を使います。なお公式リファレンスには、「中身が1つのオブジェクトだけの配列」を渡すと、コールバックにはその配列ではなくオブジェクトが渡る、という注意書きがあります。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • 上記の手順1・2のコードのまま mytheme_render_card( 7, 'Hello <b>' ) を実行した出力:[before id=7]<div class="card card--7">Hello &lt;b&gt;</div>。タイトルはエスケープされ、フィルターでクラスが追加された(執筆時の検証では、mytheme_after_card に [after] を出すコールバックを追加し、カードの後ろに出力されることも確認)。
  • 引数を1つしか受け取らない登録(accepted_args 省略)では、第1引数だけが渡された。
  • mytheme_per_page() はデフォルトの 10、フィルターが '25' を返すと (int) キャストにより int(25)。
  • 配列の引数は array-arg: A1、参照渡しは ref n=2 になった。
  • has_action は true、did_action は 1。

ログは testscreate-custom-hook-do-action-apply-filters.md にあります。「配列に入った単一オブジェクト」の挙動は、この環境では検証していません(公式の記載のみに基づきます)。

独自フックの作り方の注意点

  • フィルターの戻り値は、(int) などで型を整えてから使うと安全です。使う側が文字列を返すこともあるためです。
  • フックに渡す値のエスケープは、出力する側で行う設計に統一します。フィルター後の HTML を echo する場合は、wp_kses_post() などで通す判断を明示します。
  • 一度公開したフック名・引数の順番は、変更すると他の人のコードが壊れます。引数は末尾に足すのが基本です。
  • フック名は、小文字とアンダースコアで、接頭辞を付けます。init のような汎用名は使いません。

独自フックの作り方でよくあるミス

  • apply_filters() の戻り値を受け取らず、結果が反映されない。
  • 利用側が add_filter() の第4引数を指定せず、第2引数以降を受け取れない(add_filter() の使い方|説明・引数・注意点参照)。
  • フック名に接頭辞を付けず、他のプラグインと衝突する。
  • フィルターの結果を、エスケープせず出力して、脆弱性になる。

独自フックの作り方のチェックリスト

  • フック名に、固有の接頭辞を付けたか
  • アクションかフィルターか、目的で選んだか
  • 渡す引数が、使う側の判断に十分か
  • 戻り値の型を整えて使っているか
  • 出力前のエスケープ方針を決めたか

独自フックの作り方のFAQ(よくある質問)

Q. フックを作ったことを、利用者にどう伝えますか?
A. ドキュメントに、フック名・引数・戻り値の型・使用例を書くのが一般的です。

Q. 条件によってフック名を変えられますか?
A. 可能です。コアにも {$taxonomy}_add_form のように動的な名前があります。ただし検索しづらくなるため、乱用は避けます。

Q. do_action の代わりに関数を直接呼んでもよいですか?
A. 利用者が差し込む必要がなければ、直接呼んで構いません。拡張点が必要な箇所だけにフックを置きます。

筆者の見解(独自フックの作り方)

フックは「あとで必要になるかも」で置くより、実際に自分のテーマで2か所以上から差し替えたくなってから置く方が、設計として健全だと考えます。公開した後で引数を変えられないため、最初の引数は少なく、IDなど変わりにくいものにするのが無難だと思います。

独自フックの作り方の関連項目

出典(一次情報)

]]>
WordPressのフックの実行順|init・wp_head・wp_footer の流れ https://wordpress.ks-product.com/3082/ Thu, 05 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3082 結論

フロントエンド(サイトの表示)の大まかな実行順は次のとおりです。

  1. muplugins_loaded → plugins_loaded
  2. setup_theme → after_setup_theme
  3. init
  4. wp_loaded
  5. parse_request → wp(クエリ確定後)
  6. template_redirect
  7. wp_head(この中で wp_enqueue_scripts が優先度1で動く)
  8. 本文の出力(テンプレート)
  9. wp_footer
  10. shutdown

「どのフックに書くか」は、必要な情報がそろう最初のフックを選ぶのが原則です。例:投稿タイプの登録は init、テーマ機能の宣言は after_setup_theme、CSS・JS の読み込みは wp_enqueue_scripts、リダイレクトは template_redirect。

原因・仕組み

WordPress は wp-settings.php の中で、プラグイン、テーマの順に読み込みながら、決まった場所で do_action() を実行します。実際にコアのソースを確認すると、wp-settings.php には muplugins_loaded → plugins_loaded → sanitize_comment_cookies → setup_theme → after_setup_theme → init → wp_loaded の順で並んでいます。その後、テンプレート読み込み(template-loader.php)で template_redirect が実行されます。

つまり、順番が違うフックに書くと、「まだ関数が使えない」「条件分岐タグが正しく動かない」といった問題が起きます。たとえば is_single() は、クエリが確定する wp 以降(実用上は template_redirect や wp_enqueue_scripts)でないと、正しい値を返しません。

手順(サンプルコード)

1. どの時点で何が済んでいるか確認する

foreach ( array( 'plugins_loaded', 'after_setup_theme', 'init', 'wp_loaded' ) as $h ) {
    echo $h . '=' . did_action( $h ) . ' ';
}

did_action() は、そのフックが何回実行済みかを返します。init に書いたコードなら、plugins_loaded と after_setup_theme は 1 になっています。

2. フロントのフックの順番を記録する

$order = array();
$track = array( 'template_redirect', 'wp_enqueue_scripts', 'wp_head', 'wp_footer' );
foreach ( $track as $h ) {
    add_action( $h, function () use ( &$order, $h ) { $order[] = $h; }, -9999 );
}
do_action( 'template_redirect' );
ob_start(); wp_head(); ob_get_clean();
ob_start(); wp_footer(); ob_get_clean();
echo implode( ' > ', $order );

3. 用途別の書き場所

やりたいこと 書くフック
投稿タイプ・タクソノミーの登録 init
add_theme_support、メニュー場所の登録 after_setup_theme
CSS・JS の読み込み wp_enqueue_scripts
条件に応じたリダイレクト template_redirect
<head> への出力 wp_head
管理画面の初期化 admin_init

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で確認しました。

  • スニペットは init と wp_loaded の後に実行されるため、did_action は plugins_loaded=1 after_setup_theme=1 init=1 wp_loaded=1。
  • 記録の結果:template_redirect > wp_head > wp_enqueue_scripts > wp_footer。wp_head 自体に優先度 -9999 で登録したため先に記録され、その後に wp_enqueue_scripts が実行された。これは、コア(default-filters.php)に add_action( 'wp_head', 'wp_enqueue_scripts', 1 ) があるためで、has_action( 'wp_head', 'wp_enqueue_scripts' ) は 1 を返した。
  • wp-settings.php の do_action の並びも目視で確認した。

ブラウザでの表示は、この環境では行えないため、template_redirect と wp_head などはスニペットから手動で実行した結果です。実際のリクエストでの完全な順序は、公式のアクションリファレンスで確認してください。

WordPressのフックの実行順の注意点

  • wp_head に直接 <link> を出力するより、wp_enqueue_scripts でキューに入れるのが基本です。
  • init の時点では、is_page() のようなクエリ依存の条件分岐タグは正しく動きません。クエリが確定する wp 以降のフックを選びます。
  • 管理画面では admin_init、Ajax では wp_ajax_* など、リクエストの種類で流れが違います。
  • プラグインから after_setup_theme のフックを使う場合、テーマ側の処理との前後に注意が必要です。

WordPressのフックの実行順でよくあるミス

  • functions.php の直下で register_post_type() を呼び、init を待たない。
  • after_setup_theme より前に、add_theme_support を呼んで反映されない。
  • wp_enqueue_scripts の中で、まだ確定していない情報に依存する。
  • plugins_loaded の時点で、$wp_query や is_single() を使う。

WordPressのフックの実行順のチェックリスト

  • 使いたい関数・情報が、そのフックの時点で使えるか公式で確認したか
  • did_action() で、先に実行済みのフックを確認したか
  • 優先度の指定が、他のコードとの前後関係に合っているか
  • フロントと管理画面で、必要なフックを分けているか
  • 実行順をログに出して確認したか

WordPressのフックの実行順のFAQ(よくある質問)

Q. init と wp_loaded の違いは?
A. wp_loaded は init の後、WordPress が完全に読み込まれた時点です。クエリ関連の処理は、さらに後の wp 以降です。

Q. wp_enqueue_scripts が wp_head の中で動くのは、なぜ問題にならないのですか?
A. コアが wp_head の優先度1で呼ぶ仕様のためです。wp_head で出力する前に、キューが整います。

Q. 実行順を自分の環境で見るには?
A. 先頭で add_action( 'all', ... ) を登録して、current_filter() を記録する方法があります。ただし出力が多いため、本番では使いません。

筆者の見解(WordPressのフックの実行順)

フックの順番は、暗記するより「コアのソースに当たる」習慣を持つ方が、結局は早いと考えます。wp-settings.php と default-filters.php を一度読むと、なぜ init に書くのかが腑に落ちます。迷ったときに、did_action() で状態を確かめる癖をつけるのがおすすめです。

WordPressのフックの実行順の関連項目

出典(一次情報)

]]>
add_action の優先度の決め方|10・99・PHP_INT_MAX の使い分け https://wordpress.ks-product.com/3081/ Tue, 03 Nov 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3081 結論

優先度($priority)は、数値が小さいほど先に実行される整数で、省略すると 10 です。決め方の基本は次の3つだけです。

  • 他のコードと関係なければ、省略(10)でよい。
  • 他のコードの前に何かしたいなら、それより小さい数(1〜9)。
  • 他のコードの後で上書き・結果の確認をしたいなら、それより大きい数(11〜99、最後に確実に動かしたいなら大きな値)。

大切なのは「何の前後に動かしたいか」を先に決め、基準となるコールバックの優先度を has_action() / has_filter() で調べてから数値を選ぶことです。

原因・仕組み

WordPress は、1つのフックに登録されたコールバックを、優先度の小さい順に実行します。同じ優先度の中では登録した順です(公式の add_action() リファレンスにも同じ説明があります)。

注意したいのは、優先度が「絶対的な時刻」ではなく、「そのフックの中での相対的な並び順」でしかない点です。だから、100 を指定しても、他のプラグインが 999 を指定していれば、そちらが後です。

手順(サンプルコード)

1. 実行順を確認する

add_action( 'demo', function () { echo 'A'; } );             // 10(省略)
add_action( 'demo', function () { echo 'B'; } );             // 10(Aの後)
add_action( 'demo', function () { echo 'C'; }, 1 );          // 1
add_action( 'demo', function () { echo 'D'; }, PHP_INT_MAX );
add_action( 'demo', function () { echo 'E'; }, -5 );        // 負の値も使える
do_action( 'demo' );
// E > C > A > B > D の順

2. フィルターの結果を後から上書きする

add_filter( 'the_demo', function ( $v ) { return $v . '[theme10]'; } );
add_filter( 'the_demo', function ( $v ) { return $v . '[plugin99]'; }, 99 );
add_filter( 'the_demo', function ( $v ) { return $v . '[early5]'; }, 5 );
echo apply_filters( 'the_demo', 'x' );
// x[early5][theme10][plugin99]

フィルターは前のコールバックの戻り値が次の入力になります。自分の処理の前に何が済んでいるかで、受け取る値が変わります。

3. 基準の優先度を調べる

foreach ( array( 'wpautop', 'do_shortcode', 'wp_filter_content_tags', 'convert_smilies' ) as $f ) {
    echo $f . ' => ' . var_export( has_filter( 'the_content', $f ), true ) . "n";
}

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI 環境で実行しました。

  • 手順1:E(-5) > C(1) > A(10) > B(10) > D(PHP_INT_MAX) の順で実行された(負の値も有効、同じ優先度は登録順)。
  • 手順2:x[early5][theme10][plugin99]。
  • 手順3:the_content の標準値は、wpautop が 10、do_shortcode が 11、wp_filter_content_tags が 12、convert_smilies が 20、capital_P_dangit が 11 だった(この環境のコアでの値。バージョンで変わる可能性があるため、必ず自分の環境で has_filter を確認してください)。
  • 実行中に同じフック・同じ優先度へ別のコールバックを追加した場合、その回では実行されなかった(1回目の実行は「first」のみ)。優先度 20 のように後ろの優先度に追加した場合は実行された。

検証ログは testsadd-action-priority-how-to-decide.md にあります。

add_action の優先度の決め方の注意点

  • 「とりあえず 9999」は、他のコードが同じことをすると崩れます。目的が「他の処理の後」であれば、基準より 1 だけ大きい数にするのが、意図が伝わります。
  • the_content で do_shortcode(11)の前後どちらで処理するかで、ショートコードの展開前後の HTML を受け取るかが変わります。
  • 優先度は整数として扱われます。小数は使わず、整数だけを指定します(リファレンスの型も int です)。

add_action の優先度の決め方でよくあるミス

  • wpautop(10)より前に整形したいのに、10 のまま登録して、順序が登録順任せになる。
  • 優先度を変えて登録したのに、remove_action 側で優先度を合わせていない(remove_action() の使い方|説明・引数・注意点参照)。
  • 上書きしたいだけなのに、非常に大きな数を使い、後から他のプラグインと競合する。
  • アクションの実行中に、同じ優先度へ追加して「実行されない」と悩む。

add_action の優先度の決め方のチェックリスト

  • 「何の前、何の後」に動かしたいか、言葉で書けるか
  • 基準のコールバックの優先度を has_filter / has_action で調べたか
  • 数値を、基準の前後を示す最小の変更にしているか
  • 実行順を、error_log やテストで確認したか
  • 削除処理の優先度が、登録と一致しているか

add_action の優先度の決め方のFAQ(よくある質問)

Q. 優先度の上限はありますか?
A. 実務では PHP の整数の範囲です。PHP_INT_MAX も使えます。

Q. 同じ優先度のコールバックを確実に先にしたいときは?
A. 優先度をずらすのが確実です。登録順は、読み込み順に依存するため不安定です。

Q. アクションでも優先度は同じ意味ですか?
A. 同じです。add_action は add_filter と同じ仕組みで、戻り値を使わないだけです。

筆者の見解(add_action の優先度の決め方)

優先度は「数字の大きさを競うもの」ではなく、「どのコードの隣に置くか」を表すものだと考えます。迷ったときは、まず 10 のまま動かし、順序が問題になったときだけ基準を調べて決める方が、後から読みやすいコードになると思います。

add_action の優先度の決め方の関連項目

出典(一次情報)

]]>
WordPress プラグイン自作の方法|最小構成のファイルと有効化・停止・削除の書き方 https://wordpress.ks-product.com/3176/ Wed, 21 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3176 結論

WordPress のプラグイン自作は、wp-content/plugins/ にフォルダを1つ作り、その中の PHP ファイルに「Plugin Name」を含むヘッダーコメントを書くだけで始められます。これで管理画面の「プラグイン」一覧に表示され、有効化できるようになります。

実用に耐える最小構成は次の4点です。

  1. フォルダとメインファイル(my-plugin/my-plugin.php)にヘッダーコメント
  2. ファイル先頭で ABSPATH を確認し、直接アクセスを防ぐ
  3. 関数・オプション名に独自の接頭辞を付ける
  4. 必要に応じて、有効化(register_activation_hook())・停止(register_deactivation_hook())・削除(uninstall.php)の処理を用意する

テーマの functions.php に書く方法との違いは、テーマを変えても機能が残ることです。サイトの見た目に関係しない機能(お知らせの表示、独自の投稿タイプ、外部サービス連携など)はプラグインにしておくと、テーマの入れ替えで機能が消える事故を防げます。

原因・仕組み

WordPress は wp-content/plugins/ 以下のファイルのヘッダーコメントを読み、プラグインとして認識します。Plugin Handbook の Header Requirements によると、必須なのは Plugin Name だけで、ほかに Description、Version、Requires at least(最小の WordPress 版)、Requires PHP(最小の PHP 版)、Author、License、Text Domain、Update URI、Requires Plugins(依存プラグインのスラッグ)などを書けます。Version は PHP の version_compare() で比べられるため、新しい版が大きくなる形式で付けます。

また、Plugin Basics は「ヘッダーコメントを持つファイルはフォルダ内に1つだけにする」としています。

有効化・停止・削除のタイミングで動く処理は役割が分かれています。

タイミング 書き方 主な用途(Handbook の説明)
有効化 register_activation_hook() 初期値の保存、パーマリンクの更新など
停止 register_deactivation_hook() キャッシュなど一時データの削除
削除 uninstall.php または register_uninstall_hook() オプションや独自テーブルなど、データの完全な削除

手順(サンプルコード)

管理画面に一行のお知らせを出すだけのプラグインです。wp-content/plugins/ks-hello-notice/ks-hello-notice.php として保存します。

<?php
/*
 * Plugin Name:       KS Hello Notice
 * Description:       管理画面に一行のお知らせを出すサンプル。
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * Author:            Example
 * License:           GPL-2.0-or-later
 * Text Domain:       ks-hello-notice
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // WordPress 経由以外での直接アクセスを止める
}

function ks_hello_notice_activate() {
    add_option( 'ks_hello_notice_message', 'こんにちは' );
}
register_activation_hook( __FILE__, 'ks_hello_notice_activate' );

function ks_hello_notice_deactivate() {
    delete_transient( 'ks_hello_notice_cache' );
}
register_deactivation_hook( __FILE__, 'ks_hello_notice_deactivate' );

function ks_hello_notice_render() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    $msg = get_option( 'ks_hello_notice_message', '' );
    printf( '<div class="notice notice-info"><p>%s</p></div>', esc_html( $msg ) );
}
add_action( 'admin_notices', 'ks_hello_notice_render' );

同じフォルダに uninstall.php を置くと、管理画面で「削除」したときに実行されます。

<?php
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    exit;
}
delete_option( 'ks_hello_notice_message' );

ファイルが増えてきたら、Best Practices の例のように includes/・admin/・public/・languages/ へ分け、メインファイルから require_once plugin_dir_path( __FILE__ ) . 'includes/....php'; で読み込みます。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)/PHP 8.2.12 の CLI 検証環境で、上の2ファイルを実際に wp-content/plugins/ に作り、get_plugin_data()・activate_plugin()・deactivate_plugins()・uninstall_plugin() を順に呼びました(php run.php wl2_plugin.php、ログは tests/plugin-create-minimum-structure.md)。

Name=KS Hello Notice Version=1.0.0 RequiresWP=6.5 RequiresPHP=7.4 TextDomain=ks-hello-notice
listed=yes
activate=NULL
is_active=true
option=こんにちは
notice=<div class="notice notice-info"><p>こんにちは</p></div>
after deactivate is_active=false
has_uninstall=true
after uninstall option=false
cleanup=true
  • ヘッダーの各項目が読み取られ、get_plugins() の一覧に載りました。
  • 有効化で有効化フックが動き、オプションが保存されました。admin_notices を発火させると、エスケープ済みのお知らせが出力されました。
  • 停止後は無効になり、uninstall.php があるため削除可能と判定され、削除処理でオプションが消えました。最後にフォルダごと片付けています。
  • ブラウザでの管理画面表示はこの環境では確認していません(関数を直接呼んで確認)。

WordPress プラグイン自作の方法の注意点

  • 関数名・オプション名には、wp_ などの WordPress 本体の接頭辞を避け、4〜5文字以上の独自の接頭辞を付けます(Best Practices の推奨)。名前が他のプラグインとぶつかると、致命的エラーで画面が真っ白になります。
  • uninstall.php では必ず WP_UNINSTALL_PLUGIN を確認します。なお Handbook によると、register_uninstall_hook() 経由のときはこの定数は定義されません。
  • 停止フックでユーザーのデータを消さないでください。停止は一時的なことが多く、設定まで消すと再有効化のときに困ります。
  • 画面に出す値はエスケープし、保存や変更を伴う処理には権限確認(current_user_can())と nonce を入れます。

WordPress プラグイン自作の方法でよくあるミス

  • ヘッダーを書いたファイルをフォルダの中に2つ作り、一覧に二重に出る。
  • register_activation_hook() を init などのフックの中で呼び、有効化時に登録されていない。メインファイルの直下で呼びます。
  • 有効化フックで出力(echo)をして、「予期しない出力が発生しました」の警告を出す。
  • 接頭辞なしの function notice() のような名前を付け、別のプラグインと衝突する。

WordPress プラグイン自作の方法のチェックリスト

  • wp-content/plugins/<フォルダ>/<同名>.php に Plugin Name を書いた
  • 先頭で ABSPATH を確認している
  • 関数・オプション・定数に独自の接頭辞を付けた
  • 出力はエスケープ、変更処理は権限と nonce を確認している
  • 停止で消すのは一時データだけにした
  • 削除時の処理(uninstall.php)を用意した
  • Requires at least / Requires PHP を実際に動く版で書いた

WordPress プラグイン自作の方法のFAQ(よくある質問)

Q. functions.php に書くのとプラグインにするのは、どう使い分けますか。
A. 見た目(テーマ)に依存する処理は functions.php、テーマを変えても残したい機能はプラグインにするのが目安です。

Q. 1ファイルだけのプラグインも作れますか。
A. 作れます。wp-content/plugins/ 直下に1ファイルで置いても認識されますが、後からファイルが増えるのでフォルダにしておくのがおすすめです。

Q. 必ず読み込ませたい場合は。
A. wp-content/mu-plugins/ に置くと、有効化操作なしで常に読み込まれます(停止できない点に注意)。

筆者の見解(WordPress プラグイン自作の方法)

プラグイン自作の入口は意外なほど小さく、ヘッダー1つで動き始めます。だからこそ、私見では最初の1本から「直接アクセス防止」「接頭辞」「エスケープと権限確認」「削除時の後片付け」の4つを型として書いておくことが大切だと考えます。小さなお知らせ表示でも、この型を守っておけば、機能が増えたときにそのまま育てられます。

WordPress プラグイン自作の方法の関連項目

出典(一次情報)

]]>
remove_action が効かない原因と対処|優先度・タイミング・クラス https://wordpress.ks-product.com/3050/ Mon, 05 Oct 2026 15:03:00 +0000 https://wordpress.ks-product.com/3050/ 結論

remove_action() が効かないときの原因は、ほぼ次の4つに絞れます。

  1. 優先度が一致していない(追加側が 20 なのに、削除側は省略=10)
  2. 削除を書いた場所が早すぎる(追加される前に実行している)、または遅すぎる(フックがすでに実行された後)
  3. クラスメソッドを、インスタンスではなく文字列のクラス名で指定している
  4. クロージャ(無名関数)で追加されている

remove_action() は、外せなかったときに警告もエラーも出さず、戻り値 false を返すだけです。そのため、「書いたのに何も起きない」状態になりやすいのが特徴です。

原因・仕組み

remove_action() は remove_filter() の別名で、内部では「フック名・コールバック・優先度」の3つがすべて一致する登録を探して削除します(公式リファレンスにも、優先度は追加時と完全に一致させる旨の記載があります)。つまり「だいたい合っている」では外れません。

また、WordPress のフックは「登録された順に配列へ入れ、実行時にその配列を回す」仕組みです。登録されていないものは外せませんし、すでに実行済みのフックから外しても、その回の処理には間に合いません。

remove_actionは、add_actionで追加された後、そのフックが実行される前に、同じ優先度で呼ぶ必要がある削除は「追加された後」かつ「フックが実行される前」にplugins_loadedafter_setup_themeinit(実行)add_action(… , 20)ここで remove_action・優先度を追加時と同じに(20 で追加 → 20 で削除)・クラスのメソッドはインスタンスで指定。クロージャは外せない・外せなくても警告は出ず、false が返るだけ
フックの名前・コールバック・優先度の3つがすべて一致する登録だけが削除される。時系列は一例で、実際は追加している側のタイミングを確認する。

手順(サンプルコード)

1. 優先度を合わせる

function greet() { echo "hellon"; }
add_action( 'demo_hook', 'greet', 20 );

remove_action( 'demo_hook', 'greet' );      // 優先度10と解釈され、外れない(false)
remove_action( 'demo_hook', 'greet', 20 );  // 追加時と同じ20なので外れる(true)

相手のコードで優先度が分からないときは、has_action( 'demo_hook', 'greet' ) を使います。登録されていればその優先度の数値が、なければ false が返ります。

2. 登録の後・実行の前に外す

// 外したい側(テーマやプラグイン)
add_action( 'after_setup_theme', function () {
    remove_action( 'wp_head', 'wp_generator' ); // wp_head が実行される前に外す
} );

追加元が plugins_loaded や init で登録している場合は、それより後のフック(もしくは同じフックで大きい優先度)で外します。

add_action( 'init', function () {
    remove_action( 'template_redirect', 'plugin_redirect_func', 10 );
}, 99 );

3. クラスメソッドはインスタンスで指定する

class Plugin_X {
    public function __construct() { add_action( 'demo_hook2', array( $this, 'run' ) ); }
    public function run() { echo "runn"; }
}
$GLOBALS['plugin_x'] = new Plugin_X();

remove_action( 'demo_hook2', array( 'Plugin_X', 'run' ) );            // false:外れない
remove_action( 'demo_hook2', array( $GLOBALS['plugin_x'], 'run' ) );  // true:外れる

インスタンスをグローバル変数や静的プロパティで参照できない場合は、自分でそのコードを書き換えるのではなく、作者が用意しているフィルターや設定項目がないかを先に探します。

4. クロージャは基本的に外せない

クロージャは毎回別のオブジェクトになるため、同じ見た目の無名関数を書いても外れません。最終手段として remove_all_actions( 'フック名' )(優先度の指定も可)がありますが、他のコールバックも消えるため、影響範囲を確認してから使います。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)、PHP 8.2.12 の CLI テスト環境で実行しました(C:Tempwp-testrun.php に上記のコードを渡して実行)。

  • 登録前の remove_action を書いた後に add_action(..., 20) → has_action は 20(まだ登録されている)
  • 優先度省略の remove_action → false、has_action は 20 のまま
  • 優先度 20 を指定 → true、has_action は false
  • クラス名文字列での指定 → false、インスタンス指定 → true
  • 別のクロージャで外そうとした → false、remove_all_actions → 全削除
  • 別のフック(timing_a)のコールバックで demo_late の登録を、do_action( 'demo_late' ) の前に外した → 外れて実行されなかった

詳細ログは testsremove-action-not-working.md に保存しています。

remove_action が効かないときの注意点

  • 他人のコードに remove_action を使うと、プラグインの更新で優先度が変わった際に、気付かないまま外れなくなることがあります。更新後の確認を習慣にしてください。
  • has_action() で事前に確認してから外すと、デバッグしやすくなります。
  • 管理画面専用のフックなど、実行される場面が限られるものは、そのコンテキストの中で外します。

remove_action が効かない原因と対処でよくあるミス

  • functions.php の最上部で、読み込み順の関係から、まだ追加されていないフックを外そうとする。
  • 追加側の優先度を確認せずに、既定値のまま外そうとする。
  • array( 'クラス名', 'メソッド' ) で外そうとする(静的メソッドでない限り無効)。
  • すでに実行された後のフック(例:wp_head の中から wp_head の登録を外す)に対して外そうとする。

remove_action が効かない原因と対処のチェックリスト

  • 追加側のコードで、フック名・関数名・優先度を確認したか
  • has_action() が、削除前に数値を返すことを確認したか
  • 削除コードは、追加の後・フックの実行前に動くか
  • クラスの場合は、インスタンスで指定しているか
  • remove_action() の戻り値を、デバッグ時に確認したか

remove_action が効かない原因と対処のFAQ(よくある質問)

Q. 戻り値が true なのに、まだ動いているのはなぜですか?
A. 同じ処理が別のフックや、別の優先度から二重に登録されている可能性があります。has_action() を複数のフックで確認してください。

Q. フィルターの場合も同じですか?
A. 同じです。remove_filter() を使い、考え方(優先度の一致・タイミング)は共通です。

Q. 子テーマで親テーマのフックを外すには?
A. 親テーマは先に読み込まれるため、子テーマの functions.php から after_setup_theme などで外します。

筆者の見解(remove_action が効かない原因と対処)

remove_action() が失敗しても何も言ってくれない点が、一番のつまずきどころだと考えます。まず has_action() で「今どの優先度で登録されているか」を表示して、数値を目で確認する方法が、遠回りに見えて最も早いと思います。なお、クロージャで書かれたコードは「外されないことを前提にした作り」とも読めるため、無理に外さず、設定項目やフィルターでの調整を探すのが穏当と私見では考えます。

remove_action が効かない原因と対処の関連項目

出典(一次情報)

]]>
shortcode_atts_{shortcode} フックの使い方|説明・引数・注意点 https://wordpress.ks-product.com/553/ https://wordpress.ks-product.com/553/#respond Fri, 02 Oct 2026 16:10:26 +0000 https://wordpress.ks-product.com/553/ 説明

shortcode_atts_{shortcode} は、指定したショートコードの属性を加工するフィルターです。

基本構文

apply_filters( 'shortcode_atts_{$shortcode}', array $out, array $pairs, array $atts, string $shortcode )

引数

  • $out:処理後の属性
  • $pairs:既定値
  • $atts:ユーザー指定の属性
  • $shortcode:ショートコード名

戻り値

属性の配列を返します。

使い方(サンプル)

add_filter( 'shortcode_atts_gallery', function( $out ) {
	$out['columns'] = 4;
	return $out;
} );

注意点

  • shortcode_atts() の第3引数にショートコード名を渡した場合のみ呼ばれます。

実務での使いどころ

  • 特定のショートコードの、属性(既定値を含む)を、外から、書き換えるとき。

よくあるミスと対策

  • shortcode_atts() の第3引数(ショートコード名)を、指定していない。このフィルターが、実行されない。
  • 配列を、返していない。
  • フック名の ショートコード名 の部分を、置き換えていない。

NG例

add_filter( 'shortcode_atts_hello', function ( $out ) {
	$out['name'] = '太郎';
} ); // 返していない

OK例

add_filter( 'shortcode_atts_hello', function ( $out, $pairs, $atts ) {
	$out['name'] = '太郎';
	return $out;
}, 10, 3 );
// ショートコード側: shortcode_atts( $pairs, $atts, 'hello' );

使い分け早見表

関数・フィルター 役割
shortcode_atts() 属性の既定値を設定する(第3引数にショートコード名を指定)
shortcode_atts_{shortcode} 特定のショートコードの属性を、書き換える
add_shortcode() ショートコードを、登録する

関連項目

shortcode_atts()、add_shortcode()

公式リファレンス:shortcode_atts_{shortcode} | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/553/feed/ 0
upload_mimes フックの使い方|説明・引数・注意点 https://wordpress.ks-product.com/552/ https://wordpress.ks-product.com/552/#respond Fri, 02 Oct 2026 16:10:25 +0000 https://wordpress.ks-product.com/552/ 説明

upload_mimes は、アップロードを許可するファイルの種類を変更するフィルターです。

基本構文

apply_filters( 'upload_mimes', array $mimes, int|WP_User|null $user )

引数

  • $mimes:拡張子とMIMEタイプの連想配列
  • $user:ユーザー

戻り値

許可するMIMEタイプの配列を返します。

使い方(サンプル)

add_filter( 'upload_mimes', function( $mimes ) {
	$mimes['svg'] = 'image/svg+xml';
	return $mimes;
} );

注意点

  • SVGなど、スクリプトを含み得る形式を許可する場合は、セキュリティに注意します。

実務での使いどころ

  • メディアにアップロードできるファイルの種類を、追加・制限するとき。

よくあるミスと対策

  • SVGなど、スクリプトを含められるファイルを、誰でもアップロードできるようにしている。管理者に限定するだけでなく、信頼できる相手のファイルに限るか、サニタイズする仕組みを使う。環境によっては、wp_check_filetype_and_ext フィルターも必要になる。
  • 配列を、返していない。
  • 追加するときは、拡張子 => MIMEタイプ の形式で指定する。既存のキーは、jpg|jpeg|jpe のように、複数の拡張子を並べた形。

NG例

add_filter( 'upload_mimes', function ( $mimes ) {
	$mimes['svg'] = 'image/svg+xml'; // 誰でもアップロードでき、返してもいない
} );

OK例

add_filter( 'upload_mimes', function ( $mimes ) {
	if ( current_user_can( 'manage_options' ) ) {
		$mimes['svg'] = 'image/svg+xml';
	}
	return $mimes;
} );

使い分け早見表

フィルター・関数 役割
upload_mimes アップロードできる種類の、一覧
wp_check_filetype() 拡張子から、MIMEタイプを判定する
wp_handle_upload() アップロードを、処理する

関連項目

wp_check_filetype()、wp_handle_upload()

公式リファレンス:upload_mimes | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/552/feed/ 0
wp_mail_from フックの使い方|説明・引数・注意点 https://wordpress.ks-product.com/551/ https://wordpress.ks-product.com/551/#respond Fri, 02 Oct 2026 16:10:23 +0000 https://wordpress.ks-product.com/551/ 説明

wp_mail_from は、メールの送信元アドレスを変更するフィルターです。

基本構文

apply_filters( 'wp_mail_from', string $from_email )

引数

  • $from_email:送信元メールアドレス

戻り値

送信元アドレスを返します。

使い方(サンプル)

add_filter( 'wp_mail_from', function() {
	return '[email protected]';
} );

注意点

  • 送信元ドメインとサーバーが一致しないと、迷惑メール扱いされやすくなります。

実務での使いどころ

  • wp_mail() で送るメールの、送信元メールアドレスを、変えるとき。

よくあるミスと対策

  • メールアドレスを、返していない。
  • 返す値が、空や不正なアドレスだと、送信に失敗する。From を個別に指定したメールにも、適用される。
  • 送信元のドメインが、サイトのドメインと違い、迷惑メールとして扱われやすい。
  • 送信元の名前を変えたいのに、使っている。名前は、wp_mail_from_name フィルター。

NG例

add_filter( 'wp_mail_from', function () {
	echo '[email protected]'; // 返さず、出力している
} );

OK例

add_filter( 'wp_mail_from', function ( $email ) {
	return '[email protected]';
} );
add_filter( 'wp_mail_from_name', function ( $name ) {
	return 'サイト名';
} );

使い分け早見表

フィルター 変更する対象
wp_mail_from 送信元のメールアドレス
wp_mail_from_name 送信元の名前
wp_mail() メールを、送る関数

関連項目

wp_mail()

公式リファレンス:wp_mail_from | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/551/feed/ 0