WordPressのカスタマイズをしていると、頻繁に登場するWP_Query。
いつも使うやつもあれば滅多に使わないものもあるので、自分用の備忘録として残しています。
WP_QueryはWordPressカスタマイズには欠かせない機能であり、これを使いこなせれば大抵のことはカスタマイズできるようになります。
頻度が高くてよく使う項目だけまとめました。
$args = array(
//◆ある投稿者に関連付けられた投稿を表示
'author' => '123',
'author_name' => 'rami',
'author__in' => array(2, 6),
'author__not_in' => array(2, 6),
//◆あるカテゴリーに関連付けられた投稿を表示
'cat' => 4,
'category_name' => 'staff',
'category__and' => array( 2, 6 ),
'category__in' => array( 2, 6 ),
'category__not_in' => array( 2, 6 ),
//◆あるタグに関連付けられた投稿を表示
'tag' => 'cooking',
'tag_id' => 13,
'tag__and' => array( 37, 47 ),
'tag__in' => array( 37, 47 ),
'tag__not_in' => array( 37, 47 ),
'tag_slug__and' => array( 'bread,baking'),
'tag_slug__in' => array( 'bread,baking'),
//◆あるタクソノミーに関連付けられた投稿を表示
'tax_query' => array(
'relation' => 'AND',
array(
'taxonomy' => 'movie_genre',
'field' => 'slug',
'terms' => array( 'action', 'comedy' ),
'include_children' => true,
'operator' => 'IN'
),
array(
'taxonomy' => 'actor',
'field' => 'term_id',
'terms' => array( 103, 115, 206 ),
'include_children' => false,
'operator' => 'NOT IN'
)
),
//◆特定のカスタムフィールドに関連付けられた投稿を表示
'meta_key' => 'key',
'meta_value' => 'value',
'meta_value_num' => 10,
'meta_compare' => '=',
'meta_query' => array(
'relation' => 'AND',
array(
'key' => 'color',
'value' => 'blue',
'type' => 'CHAR',
'compare' => '=',
),
array(
'key' => 'price',
'value' => array( 1,200 ),
'compare' => 'NOT LIKE'
)
),
//◆投稿および固定ページに基づいてコンテンツを表示
'p' => 7,
'name' => 'hello-world',
'page_id' => 7,
'pagename' => 'about-my-life',
'pagename' => 'parent_slug/child_slug',
'post_parent' => 93,
'post_parent__in' => array(2, 5, 12, 14, 20),
'post_parent__not_in' => array(2, 5, 12, 14, 20),
'post__in' => array(2, 5, 12, 14, 20),
'post__not_in' => array(2, 5, 12, 14, 20),
//◆パスワード保護の有無に応じて表示
'has_password' => true,
'post_password' => 'zxcvbn',
//◆ある投稿タイプに関連付けられた投稿を表示
'post_type' => array(
'post',
'page',
'revision',
'attachment',
'custom-post-type'
),
'post_type' => 'any',
//◆ある投稿ステータスに関連付けられた投稿を表示
'post_status' => array(
'publish', // 公開済
'pending', // レビュー待ち
'draft', // 下書き
'auto-draft', // 新規作成された投稿
'future', // 予約公開設定された投稿
'private', // 非ログインユーザーから見えない設定
'inherit', // リビジョン
'trash', // ゴミ箱に入った投稿
),
'post_status' => 'any', // trashとauto-draftを除くすべてのステータス
//◆ページ送りパラメータ
'posts_per_page' => 10,
'posts_per_archive_page' => 10,
'nopaging' => false,
'offset' => 3,
'paged' => get_query_var('paged'),
'page' => get_query_var('page'),
'ignore_sticky_posts' => false,
//◆投稿の並びを指定（順序づけ）
'order' => 'DESC',
'orderby' => 'date',
//使えるオプション値:
//'none' - 並び替えない。
//'ID' - 投稿ID順
//'author' - 著者順
//'title' - タイトル順
//'name' - 投稿スラッグ順
//'date' - 投稿日順
//'modified' - 更新日順
//'parent' - 親ページのID順
//'rand' - ランダム
//'comment_count' - コメント数順
//'menu_order' - ページの表示順
//'meta_value' - カスタムフィールド値順
//'meta_value_num' - カスタムフィールド値順（数値）
//'title menu_order' - タイトルとページの表示順
//'post__in' - post__inの配列で指定された投稿ID順
//◆特定の時間や日付の期間に基づいて投稿を表示
'year' => 2014,
'monthnum' => 4,
'w' => 25,
'day' => 17,
'hour' => 13,
'minute' => 19,
'second' => 30,
'm' => 201404,
'date_query' => array(
array(
'year' => 2014,
'month' => 4,
'week' => 31,
'day' => 5,
'hour' => 2,
'minute' => 3,
'second' => 36,
'after' => 'January 1st, 2013',
'before' => array(
'year' => 2013,
'month' => 2,
'day' => 28,
),
'inclusive' => true,
'compare' => '=',
'column' => 'post_date',
'relation' => 'AND',
),
),
//◆検索パラメータ
's' => $s,
'exact' => true,
'sentence' => true,
//◆投稿フィールドパラメータ
'fields' => 'ids',
);
$the_query = new WP_Query( $args );
// ループ
if ( $the_query->have_posts() ) :
while ( $the_query->have_posts() ) :
$the_query->the_post();
// 処理の実行
endwhile;
endif;
// 投稿データをリセット
wp_reset_postdata();
頻繁に使うWP＿Query パラメータの解説
ある投稿者に関連付けられた投稿を表示
| author | (整数|文字列) | ユーザー ID またはそのコンマ区切りリスト |
| author_name | (文字列) | ‘user_nicename’ （姓・名・ニックネームではなく） |
| author__in | (配列) | ユーザーID |
| author__not_in | (配列) | ユーザーID |
ひとりの投稿者の投稿を表示する
ユーザーIDを用いて、ある投稿者の投稿を表示する場合
$query = new WP_Query( 'author=123' );
‘user_nicename’ を用いて、ある投稿者の投稿を表示する場合
$query = new WP_Query( 'author_name=rami' );
複数の投稿者の投稿を表示する
ユーザーIDを用いて、複数の投稿者の投稿を表示する場合
$query = new WP_Query( 'author=2,6,17,38' );
‘author__in’の場合
$query = new WP_Query( array( 'author__in' => array( 2, 6 ) ) );
ある投稿者による投稿を除外する
ユーザーIDの頭に’-‘（マイナス）をつけることで、あるひとり(singular)の投稿者による投稿を除いて、すべての記事を表示できます
$query = new WP_Query( 'author=-12' );
複数のユーザーを除外したい場合
$query = new WP_Query( array( 'author__not_in' => array( 2, 6 ) ) );
あるカテゴリーに関連付けられた投稿を表示
| cat | (整数) | カテゴリーIDを使用 |
| category_name | (文字列) | カテゴリーのスラッグを使用 |
| category__and | (配列) | カテゴリーIDを使用 |
| category__in | (配列) | カテゴリーIDを使用 |
| category__not_in | (配列) | カテゴリーIDを使用 |
1つのカテゴリーの記事を表示する
カテゴリーIDを使用して、そのカテゴリー（子カテゴリー含む）に属する記事を表示
$query = new WP_Query( 'cat=4' );
カテゴリースラッグを使用して、そのカテゴリー（子カテゴリー含む）に属する記事を表示
$query = new WP_Query( 'category_name=staff' );
カテゴリー ID を使って、そのカテゴリー (子カテゴリーではない)に属する記事を表示
$query = new WP_Query( 'category__in=4' );
複数のカテゴリーから記事を表示する
カテゴリーIDを使用して、いずれかのカテゴリーに属する記事を表示
$query = new WP_Query( 'cat=2,6,17,38' );
$query = new WP_Query( array( 'category__in' => array( 2, 6 ) ) );
カテゴリースラッグを使用して、いずれかのカテゴリーに属する記事を表示
$query = new WP_Query( 'category_name=staff,news' );
指定する”全て”のカテゴリーに属する記事を表示
$query = new WP_Query( 'category_name=staff+news' );
$query = new WP_Query( array( 'category__and' => array( 2, 6 ) ) );
カテゴリーに属する記事を除外
カテゴリーIDに’-‘（マイナス）をつけることで、そのカテゴリーの記事を除くすべての記事を表示
$query = new WP_Query( 'cat=-12,-34,-56' );
‘category__not_in’を使ってカテゴリーを除外
$query = new WP_Query( array( 'category__not_in' => array( 2, 6 ) ) );
あるタグに関連付けられた投稿を表示
| tag | (文字列) | タグのスラッグを指定 |
| tag_id | (整数) | タグIDを指定 |
| tag__and | (配列) | タグIDを指定 |
| tag__in | (配列) | タグIDを指定 |
| tag__not_in | (配列) | タグIDを指定 |
| tag_slug__and | (配列) | タグのスラッグを指定 |
| tag_slug__in | (配列) | タグのスラッグを指定 |
１つのタグの記事を表示
タグIDを使って、このタグを持つ記事を表示
$query = new WP_Query( 'tag_id=13' );
タグのスラッグを使って、このタグを持つ記事を表示
$query = new WP_Query( 'tag=cooking' );
複数のタグから記事を表示
いずれかのタグを持つ記事を表示
$query = new WP_Query( 'tag=bread,baking' );
‘tag__in’を使って表示する場合
$query = new WP_Query( array( 'tag__in' => array( 37, 47 ) ) );
‘tag_slug__in’を使って表示する場合
$query = new WP_Query( array( 'tag_slug__in' => array( 'red', 'blue' ) ) );
すべてのタグを持つ記事を表示する場合
$query = new WP_Query( 'tag=bread+baking+recipe' );
‘tag__and’を使って表示する場合
$query = new WP_Query( array( 'tag__and' => array( 37, 47 ) ) );
‘tag_slug__and’を使って表示する場合
$query = new WP_Query( array( 'tag_slug__and' => array( 'red', 'blue' ) ) );
いずれのタグも持たない記事を表示する場合
$query = new WP_Query( array( 'tag__not_in' => array( 37, 47 ) ) );
あるタクソノミーに関連付けられた投稿を表示
| tax_query | (配列) | タクソノミーパラメータを使用 |
| relation | (文字列) | 2つ以上のタクソノミー条件が含まれる場合に、それらの論理的な関係を指定する。 有効な値は ‘AND’（デフォルト） または ‘OR’ 。 |
| taxonomy | (文字列) | タクソノミー |
| field | (文字列) | タクソノミータームの種類を選択。 有効な値は ‘term_id’（デフォルト）、’name’、’slug’ または ‘term_taxonomy_id’。 |
| terms | (整数/文字列/配列) | タクソノミーターム |
| include_children | (真偽値) | 階層を持つタクソノミーで子孫タクソノミーを含めるかどうか。 使用可能な値は ‘true’（デフォルト）、’false’。 |
| operator | (文字列) | 演算子。使用可能な値は ‘IN'(デフォルト), ‘NOT IN’, ‘AND’, ‘EXISTS’,‘NOT EXISTS’ |
シンプルなカスタム分類のクエリ
カスタム分類 people の bob に関連付けられた投稿（post）を表示
$args = array( 'post_type' => 'post', 'tax_query' => array( array( 'taxonomy' => 'people', 'field' => 'slug', 'terms' => 'bob', ), ), ); $query = new WP_Query( $args );
複数のカスタム分類の取り扱い
いくつかのカスタム分類から投稿を表示
$args = array( 'post_type' => 'post', 'tax_query' => array( 'relation' => 'AND', array( 'taxonomy' => 'movie_genre', 'field' => 'slug', 'terms' => array( 'action', 'comedy' ), ), array( 'taxonomy' => 'actor', 'field' => 'term_id', 'terms' => array( 103, 115, 206 ), 'operator' => 'NOT IN', ), ), ); $query = new WP_Query( $args );
カスタム分類の取扱いを入れ子で指定
より複雑なクエリを作成するために ‘tax_query’ 句を入れ子にすることができ
例: カテゴリー quotes に所属する、もしくは投稿フォーマットが quote かつカテゴリー wisdom に所属する投稿を表示
$args = array(
'post_type' => 'post',
'tax_query' => array(
'relation' => 'OR',
array(
'taxonomy' => 'category',
'field' => 'slug',
'terms' => array( 'quotes' ),
),
array(
'relation' => 'AND',
array(
'taxonomy' => 'post_format',
'field' => 'slug',
'terms' => array( 'post-format-quote' ),
),
array(
'taxonomy' => 'category',
'field' => 'slug',
'terms' => array( 'wisdom' ),
),
),
),
);
$query = new WP_Query( $args );
特定のカスタムフィールドに関連付けられた投稿を表示
| meta_key | (文字列) | カスタムフィールドのキー |
| meta_value | (文字列) | カスタムフィールドの値（文字列として比較） |
| meta_value_num | (数値) | カスタムフィールドの値（数値として比較） |
| meta_compare | (文字列) | ‘meta_value’のテスト演算子。 使える値は ‘='(デフォルト),’!=’, ‘>’, ‘>=’, ‘<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' および 'RLIKE' |
| meta_query | (配列) | カスタムフィールドの複雑なパラメータ |
| relation | (文字列) | 2つ以上のカスタムフィールド条件が含まれる場合に、それらの論理的な関係を指定する。 有効な値は ‘AND’（デフォルト） または ‘OR’ 。 |
meta_query で指定できる値
| key | (文字列) | カスタムフィールドのキー |
| value | (文字列|配列) | カスタムフィールドの値。配列を指定できるのは compare が ‘IN’, ‘NOT IN’, ‘BETWEEN’ または ‘NOT BETWEEN’ の場合のみ。 compare に ‘EXISTS’ または ‘NOT EXISTS’ を指定する場合は value を省略できる。 |
| compare | (文字列) | 演算子。使える値は ‘='(デフォルト), ‘!=’, ‘>’, ‘>=’, ‘<', '<=', 'LIKE', ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘EXISTS’ および ‘NOT EXISTS’ |
| type | (文字列) | カスタムフィールドの値のタイプ。 使える値は ‘CHAR'(デフォルト), ‘NUMERIC’, ‘BINARY’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’ |
‘type’ を 「DATE」、’compare’ を 「BETWEEN」 にして正しく比較できるのは、日付が 「YYYY-MM-DD」 形式で保存されていて、同じ形式の日付と比較する場合のみ。
簡単なカスタムフィールドクエリ
カスタムフィールドの値に関係なく、カスタムフィールドのキーが ‘color’ の投稿を表示
$query = new WP_Query( array( 'meta_key' => 'color' ) );
カスタムフィールドのキーに関係なく、カスタムフィールドの値が ‘blue’ の投稿を表示
$query = new WP_Query( array( 'meta_value' => 'blue' ) );
カスタムフィールドのキーに関係なく、カスタムフィールドの値が ‘blue’ の固定ページを表示
$args = array( 'meta_value' => 'blue', 'post_type' => 'page' ); $query = new WP_Query( $args );
カスタムフィールドのキーが ‘color’、値が ‘blue’ の投稿を表示
$args = array( 'meta_key' => 'color', 'meta_value' => 'blue' ); $query = new WP_Query( $args );
カスタムフィールドのキーが ‘color’、値が ‘blue’ ではない投稿を表示
$args = array( 'meta_key' => 'color', 'meta_value' => 'blue', 'meta_compare' => '!=' ); $query = new WP_Query( $args );
単一のカスタムフィールドの取扱い
$args = array( 'post_type' => 'product', 'meta_query' => array( array( 'key' => 'color', 'value' => 'blue', 'compare' => 'NOT LIKE' ) ) ); $query = new WP_Query( $args );
複数のカスタムフィールドの取扱い
製品（カスタム投稿タイプ ‘product’）について、色（カスタムフィールドのキー ‘color’）が青（’blue’）ではない（’NOTE LIKE’）か、または値段（キー ‘price’、タイプ ‘numeric’）が20と100の間にある（’BETWEEN’）ものを表示
$args = array( 'post_type' => 'product', 'meta_query' => array( 'relation' => 'OR', array( 'key' => 'color', 'value' => 'blue', 'compare' => 'NOT LIKE', ), array( 'key' => 'price', 'value' => array( 20, 100 ), 'type' => 'numeric', 'compare' => 'BETWEEN', ), ), ); $query = new WP_Query( $args );
‘meta_query’ 句は複雑なクエリが作れるように入れ子にできる。
$args = array(
'post_type' => 'product',
'meta_query' => array(
'relation' => 'OR',
array(
'key' => 'color',
'value' => 'orange',
'compare' => '=',
),
array(
'relation' => 'AND',
array(
'key' => 'color',
'value' => 'red',
'compare' => '=',
),
array(
'key' => 'size',
'value' => 'small',
'compare' => '=',
),
),
),
);
$query = new WP_Query( $args );
ページ送りパラメータ
| nopaging | (真偽値) | すべての投稿を含めるか、ページ送りに対応させる。 デフォルト値は false で、ページ送りに対応します。 |
| posts_per_page | (整数) | 1ページに含める投稿数。 -1 を使用するとすべての投稿を含む。 ページ送りを使用する場合は’paged’ パラメータも一緒に指定する |
| posts_per_archive_page | (整数) | 1ページに含める投稿数（アーカイブページ専用） |
| paged | (整数) | ページ番号。 |
| page | (整数) | 静的フロントページ用のページ番号 |
| ignore_sticky_posts | (真偽値) | 先頭固定表示を無視するか。true にすると無視。 |
ページあたり x 件の投稿を表示
ページあたり3件の投稿を表示
$query = new WP_Query( array( 'posts_per_page' => 3 ) );
1つのページに全ての投稿を表示
$query = new WP_Query( array( 'posts_per_page' => -1 ) );
投稿を読み飛ばす
4番目の投稿から表示
$query = new WP_Query( array( 'offset' => 3 ) );
最新から3つを飛ばして5件の投稿を表示
$query = new WP_Query( array( 'posts_per_page' => 5, 'offset' => 3 ) );
xページ目から投稿を表示
ページ番号6の記事を表示
$query = new WP_Query( array( 'paged' => 6 ) );
現在のページから投稿を表示
$query = new WP_Query( array( 'paged' => get_query_var( 'paged' ) ) );
現在のページから投稿を表示するが、もしクエリ変数がセットされていなければ（先頭ページなら）’page’ パラメータに 1 をセットする。
$paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );
静的フロントページの現在のページから投稿を表示
$paged = ( get_query_var('page') ) ? get_query_var('page') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );
順序づけパラメータ
| order | (文字列 | 配列) | ‘orderby’ パラメータについて昇順か降順かを指定します。 ASC’ – 最低から最高へ昇順 ‘DESC’ – 最高から最低へ降順(デフォルト) |
| orderby | (文字列 | 配列) | パラメータで指定した項目の値で投稿をソートする。デフォルトは ‘date’ (投稿日) |
orderbyで指定できる項目
‘none’ – 順序をつけない
‘ID’ – 投稿 ID で並び替える。※項目名は大文字。
‘author’ – 著者で並び替える。(‘post_author’ でも良い。)
‘title’ – タイトルで並び替える。(‘post_title’ でも良い。)
‘name’ – スラッグで並び替える。(‘post_name’ でも良い。)
‘type’ – 投稿タイプで並び替える。(‘post_type’ でも良い。)
‘date’ – 日付で並び替える。(‘post_date’ でも良い。)
‘modified’ – 更新日で並び替える。(‘post_modified’ でも良い。)
‘parent’ – 投稿/固定ページの親 ID 順。(‘post_parent’ でも良い。)
‘rand’ – ランダムで並び替える。
‘comment_count’ – コメント数で並び替える。
‘relevance’ – 文字列検索のとき次の順で並び替える。
1. 文字列全体がマッチ。
2. すべての単語がタイトルに含まれる。
3. いずれかの単語がタイトルに現れる。
4. 文字列全体が post_content に現れる。
‘menu_order’ – 固定ページの表示順で並び替える。
‘meta_value’ – カスタムフィールドの値を文字列順で並び替える。
‘meta_value_num’ – カスタムフィールドの値を数値順で並び替える。
‘post__in’ – post__in パラメータの配列に並んだ投稿ID順で並び替える。
‘post_name__in’ – ‘post_name__in’ パラメータの配列に並んだ投稿スラッグ順で並び替える。
‘post_parent__in’ – ‘post_parent__in’ パラメータの配列に並んだ親投稿のID順で並び替える。
タイトルで投稿をソート（降順）
$args = array( 'orderby' => 'title', 'order' => 'DESC', ); $query = new WP_Query( $args );
投稿を ‘menu_order’ の降順でソートし、値が同じなら投稿の ‘title’ の順に表示
$args = array( 'orderby' => 'menu_order title', 'order' => 'DESC', ); $query = new WP_Query( $args );
ランダムに投稿を1件表示する
$args = array( 'orderby' => 'rand', 'posts_per_page' => '1', ); $query = new WP_Query( $args );
配列を使って複数の値を ‘orderby’ に指定
別々の表示順（昇順/降順）の ‘title’ と ‘menu_order’ で並べ替え
$args = array( 'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' ) ); $query = new WP_Query( $args );
$args = array( 'orderby' => array( 'meta_value_num' => 'DESC', 'title' => 'ASC' ), 'meta_key' => 'age' ); $query = new WP_Query( $args );
カスタムフィールドとカスタム投稿タイプを ‘orderby’ に指定
投稿タイプが ‘my_custom_post_type’ で ‘age’ 順、そして ‘age’ が3か4のものだけを表示
$args = array( 'post_type' => 'my_custom_post_type', 'meta_key' => 'age', 'orderby' => 'meta_value_num', 'order' => 'ASC', 'meta_query' => array( array( 'key' => 'age', 'value' => array( 3, 4 ), 'compare' => 'IN', ), ), ); $query = new WP_Query( $args );
複数の meta_key を伴う orderby の指定
投稿メタの異なる2項目を使って並び替える
$args = array( 'meta_query' => array( 'relation' => 'AND', 'state_clause' => array( 'key' => 'state', 'value' => 'Wisconsin', ), 'city_clause' => array( 'key' => 'city', 'compare' => 'EXISTS', ), ), 'orderby' => array( 'city_clause' => 'ASC', 'state_clause' => 'DESC', ) ); $query = new WP_Query( $args );
コメント