投稿の一覧から特定のカテゴリーを外す・表示する数を変える:pre_get_posts と is_main_query

機能追加
広告WordPress・PHP を学べる本

Amazonのアソシエイトとして、WordPress functions.phpは適格販売により収入を得ています。

トップの記事の一覧から、お知らせやコラムのような特定のカテゴリーだけを外したい。一覧に出す記事の数を、トップとカテゴリーのページで変えたい。こうしたときに使うのが、pre_get_posts というフックです。

テンプレートの中で query_posts() を使っても見た目は変わりますが、ページ送りがおかしくなります。ここでは、pre_get_posts の書き方と、管理画面やサブのループまで変えてしまわない書き方を、実際に数えた数字と一緒に書きます。

コードは、このサイトの作業環境(WordPress 7.1.3・PHP 8.3)で実際に動かして確認しました。記事の数やページの数は、このサイトの記事で数えたものです。

pre_get_posts とは

WordPress は、ページを開くと、URL から「どの記事を何本出すか」を決めて、データベースから記事を読みます。このときのクエリを「メインのクエリ」と言います。

pre_get_posts は、メインのクエリがデータベースを読む直前に呼ばれるフックです。ここで条件を足すと、WordPress は変えたあとの条件で記事を読み、ページ送りの数も 404 の判定も、その条件で計算します。

コードは、テーマ(子テーマがあれば子テーマ)の functions.php に書きます。テンプレートのファイルには書きません。

いちばん大事なこと:is_admin() と is_main_query()

pre_get_posts は、メインのクエリだけでなく、すべての WP_Query で呼ばれます。管理画面の投稿の一覧、ウィジェット、関連記事、get_posts() で読む一覧も対象です。

そのため、最初に次の 2 つで「それ以外」を外します。これを忘れるのが、いちばんのつまずき所です。

functions.php(基本の形)
function my_pre_get_posts( $query ) {
    // 管理画面と、メインでないクエリは変えない
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    // ここに、変えたい条件を書く
}
add_action( 'pre_get_posts', 'my_pre_get_posts' );
書き方 役目
is_admin() 管理画面(投稿の一覧など)のときは何もしない
$query->is_main_query() メインのクエリのときだけ変える。ウィジェットや関連記事のクエリは変えない
$query->set( 名前, 値 ) クエリの条件を変える

ページの種類を見るときも、is_home() ではなく $query->is_home() のように、渡された $query のほうで見ます。is_home() は、いつもメインのクエリのことを答えるので、ほかのクエリのときにまちがえます。

確認した:2 行がないとどうなるか

作業環境で、2 行のチェックを書かずに「コラム」のカテゴリーを外すコードを置いて、前と後を比べました。サブのループは、フッターで get_posts() と new WP_Query() を呼んで試しています。

チェックのない形(まずい形)
function my_exclude_column_bad( $query ) {
    $query->set( 'category__not_in', array( 200 ) ); // 200 はコラムの ID
}
add_action( 'pre_get_posts', 'my_exclude_column_bad' );
見た所 何もしないとき チェックのない形 チェックのある形
トップの一覧(全部の記事の数) 189 179 179
管理画面の投稿の一覧(公開の記事の数) 189 179(コラムが管理画面から見えない) 189
「コラムの新着 3 本」の get_posts() 3 本 0 本 3 本
「新着 5 本」の new WP_Query() コラム 4 本を含む 5 本 コラムを含まない 5 本 コラム 4 本を含む 5 本

チェックのない形では、トップの一覧だけでなく、管理画面の投稿の一覧からもコラムが消えました。「コラムの新着」を出すつもりのサブのループは、1 本も出なくなりました。

get_posts() は、ふだんはフィルターを通さない(suppress_filters が true)関数です。それでも pre_get_posts は動くので、2 行のチェックが要ります。

特定のカテゴリーを外す

トップの一覧から、カテゴリーを外す形です。カテゴリーの ID は、管理画面の「投稿」→「カテゴリー」で、カテゴリーの編集画面を開いたときの URL の tag_ID= の数で分かります。

functions.php(トップからカテゴリーを外す)
function my_exclude_category( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( $query->is_home() ) {
        $query->set( 'category__not_in', array( 200 ) ); // 外すカテゴリーの ID
    }
}
add_action( 'pre_get_posts', 'my_exclude_category' );

外したいカテゴリーが 2 つ以上なら、array( 200, 201 ) のように並べます。記事が 2 つのカテゴリーに入っていて、その片方が外すカテゴリーなら、その記事は一覧に出ません。

category__not_in と cat に負の数の違い

カテゴリーを外す書き方は、もう 1 つあります。cat に、ID の前に「-」を付けた値を指定する形です。

cat に負の数を指定する形
$query->set( 'cat', '-200' );

2 つの違いは、子のカテゴリーまで外すかどうかです。WordPress 7.1.3 の wp-includes/class-wp-query.php では、cat の負の数は子のカテゴリーを含めて外し(include_children が true)、category__not_in は書いた ID だけを外します(false)。

作業環境で、子のカテゴリー(「WordPress 6.4.3」など)を持つ親のカテゴリー「WordPress」で試しました。記事はどれも子のカテゴリーに入っていて、親のカテゴリーに直接入っている記事はありません。

書き方 トップの一覧の記事の数 ページ送り
何もしない 189 19 ページ
category__not_in に親の ID 189(1 本も外れない) 19 ページ
cat に親の ID の負の数 19(子のカテゴリーの記事も外れる) 2 ページ

親のカテゴリーで子もまとめて外したいときは cat の負の数、その ID だけを外したいときは category__not_in を使います。思ったより記事が減った・減らないときは、この違いを疑ってください。

表示する数を変える

一覧に出す記事の数は、ふだんは管理画面の「設定」→「表示設定」の「1 ページに表示する最大投稿数」で決まります。ページの種類ごとに変えたいときは、posts_per_page を変えます。

functions.php(トップとアーカイブを 5 本に)
function my_posts_per_page( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( $query->is_home() || $query->is_archive() ) {
        $query->set( 'posts_per_page', 5 );
    }
}
add_action( 'pre_get_posts', 'my_posts_per_page' );

作業環境(表示設定は 10 本)で、トップの一覧が 5 本・38 ページになり、2 ページ目には 6 本目からの 5 本が出ました。カテゴリーのページも 5 本ずつになりました。

トップだけ変える

トップの一覧だけ、コラムを外して 6 本にする例です。$query->is_home() でないときは、すぐに戻ります。

functions.php(トップだけ)
function my_home_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( ! $query->is_home() ) {
        return;
    }
    $query->set( 'category__not_in', array( 200 ) );
    $query->set( 'posts_per_page', 6 );
}
add_action( 'pre_get_posts', 'my_home_query' );
ページ 記事の数 1 ページの本数 ページ送り
トップ 179(コラムの 10 本が外れた) 6 30 ページ(31 ページ目は 404)
カテゴリー「機能追加」 60(変わらない) 10 6 ページ
カテゴリー「コラム」 10(変わらない) 10 1 ページ

is_home() は「投稿の一覧のページ」のときに true です。表示設定でトップを固定ページにしているときは、トップではなく「投稿ページ」に決めたページで true になります。違いは「is_home() と is_front_page() の違い」にまとめています。

カテゴリーのページだけ変える

決まったカテゴリーのページだけ、1 ページに 20 本出す例です。is_category() には、ID・スラッグ・名前を渡せます。

functions.php(カテゴリー「機能追加」だけ 20 本)
function my_category_query( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( $query->is_category( 'custom' ) ) { // カテゴリーのスラッグ
        $query->set( 'posts_per_page', 20 );
    }
}
add_action( 'pre_get_posts', 'my_category_query' );
ページ 1 ページの本数 ページ送り
カテゴリー「機能追加」(60 本) 20 3 ページ(4 ページ目は 404)
カテゴリー「コラム」 10(変わらない) 1 ページ
トップ 10(変わらない) 19 ページ

すべてのカテゴリーのページを変えたいときは、$query->is_category() のように何も渡さずに書きます。カテゴリーの一覧(カテゴリーそのもの)の並び順を変えたいときは、「カテゴリーの並び順を変える」を見てください。

query_posts() を使わない理由

テンプレートの中で query_posts() を呼んでも、一覧の内容は変わります。ただし、これはメインのクエリを変えるのではなく、メインのクエリが動いたあとに、別のクエリで置き換えるものです。

index.php など(まずい形)
query_posts( 'posts_per_page=5&cat=-200' );
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // 一覧の 1 本
    endwhile;
endif;

作業環境で、テンプレートを読む前(template_redirect)に同じ query_posts() を呼んで、ページ送りを見ました。比べるために、同じ条件を pre_get_posts で書いた形も試しています。

見た所 query_posts() pre_get_posts(同じ条件)
記事の一覧を読むクエリ 2 回(もとのクエリ+置き換えたクエリ) 1 回
1 ページ目の内容 コラムを外した 5 本 同じ 5 本
2 ページ目(/page/2)の内容 1 ページ目と同じ 5 本 6 本目からの 5 本
どこまでページがあるか もとのクエリ(10 本ずつ・19 ページ)で決まる。置き換えたクエリは 36 ページ分あるのに、20 ページ目から先(30 ページ目なども)は 404 変えたあとの条件で決まる(36 ページ・37 ページ目は 404)

2 ページ目が 1 ページ目と同じになったのは、置き換えたクエリにページの番号(paged)を渡していないためです。番号を渡しても、URL が 404 になるかどうかは、もとのクエリのページの数で決まったままです。

WordPress の公式の資料(developer.wordpress.org)の query_posts() のページにも、プラグインやテーマで使わないように書かれています。一覧の条件を変えるのは pre_get_posts、別の一覧を足すのは new WP_Query() と使い分けます。

気をつける所

外した記事は、ページ送りの数に入らない

pre_get_posts で外した記事は、記事の数にもページ送りにも入りません。作業環境では、コラムを外したトップは 179 本・18 ページになり、19 ページ目は 404 になりました。

サイドバーの件数とずれる

カテゴリーの一覧や、年ごとのアーカイブの一覧の「(10)」のような件数は、pre_get_posts では変わりません。これらは WP_Query を通らずに数えているためです。

見た所(コラムをトップから外したとき) 数
トップの一覧の記事の数 179
wp_list_categories() のコラムの件数 10(変わらない)
wp_get_archives() の年ごとの件数の合計 189(変わらない)

トップから外しただけなら、カテゴリーのページや年のアーカイブには記事が出るので、件数のとおりです。アーカイブのページでも外したときは、件数とページの本数が合わなくなるので、件数を出さないか、そのカテゴリーをウィジェットから外します。

テーマやプラグインの pre_get_posts とぶつかる

テーマやプラグインにも、pre_get_posts を使っているものがあります。このサイトのテーマにも、お知らせのアーカイブの本数を変えるものなどがありました。

思ったとおりに変わらないときは、テーマの中を探して、同じページで同じ条件を変えていないかを見ます。あとから呼ばれたほうが勝つので、add_action( 'pre_get_posts', 'my_pre_get_posts', 20 ); のように順番の数を大きくすると、あとで動かせます。

テーマの中で pre_get_posts を使っている所を探す
grep -rn "pre_get_posts" --include=*.php wp-content/themes wp-content/plugins

一覧ではなく、検索のフォームでカテゴリーを絞りたいときは「カテゴリで絞り込める検索フォーム」を見てください。こちらは、検索のクエリにカテゴリーの条件を足す形です。

まとめ

一覧の条件は query_posts() ではなく pre_get_posts で変え、最初に is_admin() と is_main_query() で管理画面とサブのループを外しておきます。

参考

SiteBeacon(サイトビーコン)

サイトが止まったら、すぐに気づける。

ホームページを 5 分ごとにチェックして、止まったとき・エラーが出たとき・SSL やドメインの期限が近いときに、メールでお知らせします。2 サイトまでは、ずっと無料で使えます。

SiteBeacon を見る サイトを直す相談をする

監視で気づいたあとの直す作業も、同じ担当がお受けします。