WP_Query 実装用語pre_get_posts

pre_get_posts は、WP_Query の結果が取得される前に処理を差し込むためのフックです。すでに WordPress が用意しているページ本体のクエリを調整したい時に使われます。

初心者が最初に押さえるべきなのは、pre_get_posts は「新しい一覧を追加するためのもの」ではなく、「既存のクエリ条件を実行前に変えるためのもの」だという点です。関連記事やサイドバーの別一覧を作る場合は、独自 WP_Query のほうが自然なことがあります。

pre_get_posts は何をするフックか

pre_get_posts は、クエリが実行される前に呼ばれるフックです。フックに渡される $query オブジェクトに対して、set() を使って条件を変更できます。

たとえば、検索結果の表示件数を10件にしたり、アーカイブで特定の投稿タイプを含めたり、一覧の並び順を変えたりできます。

ここで大事なのは、pre_get_posts は影響範囲が広くなりやすいということです。対象を絞らずに条件を変更すると、管理画面やサイドバーの一覧、別の独自クエリまで変わる原因になります。

そのため、is_admin() と is_main_query() の確認をセットで考えます。ページ本体のクエリだけを変えたいのか、別のクエリも含めたいのかを先に決めます。

is_main_query() を確認する理由

pre_get_posts では、is_main_query() の確認が重要です。同じページ内には、main query だけでなく、サイドバーや関連記事などの独自クエリが存在することがあります。

対象を絞らないと、これらの独自クエリにも変更がかかる可能性があります。ページ本体の一覧だけを変えたいなら、main query に限定します。

is_main_query() は、現在扱っているクエリが WordPress の主要なクエリかどうかを確認するためのものです。関数ではなく $query->is_main_query() として使う形を意識します。

pre_get_posts の動作を確認する時は、まず変更対象を小さくします。検索結果だけ、アーカイブだけ、特定の投稿タイプだけ、というように範囲を絞ります。

Builder での扱い

WP Query Builder では、pre_get_posts は通常の独自 WP_Query 生成とは分けて扱う想定です。新しい一覧を追加する場合は custom query のコード、既存一覧を調整する場合は pre_get_posts のコード、という切り分けが必要です。

初心者向けには、「既存の一覧を変える」か「新しい一覧を追加する」かを最初に選ばせると分かりやすくなります。前者では pre_get_posts、後者では WP_Query の生成が候補になります。

生成コードでは、is_admin() と $query->is_main_query() のチェックを省略しないことが重要です。さらに、検索結果だけ、アーカイブだけ、特定の投稿タイプだけ、といった条件分岐も必要に応じて追加します。

使いどころ・避けどころと実践確認

WordPressが実行する前のメインクエリ条件を、対象画面へ限定して変更したい時に使います。

テンプレート内で独自一覧を作るだけの場合や、対象判定なしで全クエリを書き換える使い方は避けます。

管理画面、メインクエリ、アーカイブ種別のガードが不足すると、別画面や内部クエリまで影響します。

変更したいURLを一つ挙げ、変えてはいけないURLも一つ挙げると、条件分岐の漏れを見つけやすくなります。

対象・非対象URLでフック前後のクエリ変数と表示された投稿IDを記録し、変更範囲が意図した画面だけか確認します。

実践記事で確認query_postsを使わないほうがいい理由

query_posts() との違い、is_main_query() を含む安全なガード条件を実践例で確認できます。

記事を読む →

WordPressの仕様で確認するポイント

公式資料では、pre_get_posts フックのリファレンスで、クエリ実行前に条件を変更する方法を確認できます。WP_Query のリファレンスでは、変更できる引数の種類を確認できます。

また、is_main_query() の公式リファレンスを確認すると、main query だけを対象にする考え方を理解しやすくなります。

pre_get_posts は、WordPress が投稿を取得する前にクエリ条件を調整するためのフックです。既存のアーカイブや検索結果など、main query の条件を変えたい時に使うことがあります。

迷った時は、既存一覧を変えたいのか、追加一覧を作りたいのかを先に分けます。既存一覧なら pre_get_posts、追加一覧なら独自 WP_Query を検討します。