add_filter で return を忘れると｜空表示・NULL の原因と対処

結論

フィルターのコールバックは、必ず値を 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 を忘れたときの関連項目

• add_filter() の使い方｜説明・引数・注意点
• apply_filters() の使い方｜説明・引数・注意点
• remove_filter() の使い方｜説明・引数・注意点
• has_filter() の使い方｜説明・引数・注意点
• add_action() の使い方｜説明・引数・注意点