WP_Query パラメーターpost__in

どういう時に使うか

編集画面で選んだおすすめ記事、外部処理が返した投稿ID、手動で確定した掲載候補などをまとめて取得する時に使います。

空配列を渡した時の挙動を『0件になる』と決めつけないでください。呼び出し前に空かを判定し、クエリ自体を実行しない方が確実です。

IDは整数へ整形し、閲覧権限や post_status の条件も別に確認します。IDがあるだけで公開可能とは限りません。

近い引数との違い

post__in は含めるID、post__not_in は除外するIDです。WP_Query では両方を同じクエリへ併用できません。

orderby => ‘post__in’ は、指定したID配列の順序を並び順として使う指定です。post__in 単独ではその順序は保証されません。

Builderでの扱い

WP Query Builder ではIDを複数入力できます。空欄や0、重複IDを整理してから配列へ出力します。

手動順を使う選択肢を出す場合は、orderby=post__in もセットで生成されることを画面に示します。

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

選択した投稿IDだけを対象にする、手動推薦や固定リストのような要件に使います。

除外用の post__not_in と同じIDを同時指定したり、スラッグ配列を渡したりしません。

配列が空になるケースでは意図せず全件へ広がる可能性を考え、実行前に空入力を処理します。

手動で選んだ順番も守りたい場合は、IDを絞るだけでなく orderby => ‘post__in’ までが一組です。

存在するID、存在しないID、空配列、複数IDを試し、取得できた投稿IDと順序をケースごとに記録します。

実践記事で確認WP_Queryで投稿が表示されない時に見るチェックリスト

ID条件を追加して0件または想定外の全件になった時の切り分け順を確認できます。

記事を読む →

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

公式の Post & Page Parameters で、配列指定と post__not_in との併用不可を確認します。

Order & Orderby Parameters では、入力順を保つ post__in の並び指定を確認できます。

最後は、値を変える目的と、変えた時に失う情報を一緒に確認します。