メニュー

WEBMEMOする。とあるクリエイターの個人的な備忘録。

WordPressで必須知識と言っても過言ではない、WP_Queryの扱い方。ソートしたい時にかなり自由に扱えるWP_Queryは万能だからこそ、全部は覚えてはいられずにいつもググりながら使用していました。

なので、今後はここだけ見れば済むようにまとめておきます。

目次

    WP_Queryの基本の使い方

    とりあえず基本的な使い方。いつもこれをコピペしてから引数をいじってます。

    <?php
    //$argsの中身を変えていく
    $args = array(
        'post_type' => 'post', 
        'posts_per_page' => -1
     );
    
    $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();
    ?>

    配列$argsに取得したい記事に関する情報を入れ、WP_Queryを呼び出してループさせます。’posts_per_page’ はこの後にもメモしていますが、1ページにループさせる回数です。(-1で全てループ)

    予期せぬエラーを防止するため、ループが終われば wp_reset_postdata() で情報をリセットしておくのを忘れずに。

    基本(よく使うやつ)

    投稿タイプ・投稿ステータス

    投稿のタイプやステータスを指定する。

    ‘post_type’(string / array)
    投稿を投稿タイプによって取得する。デフォルト値は ‘post’。’tax_query’ がクエリーにセットされている場合、デフォルト値は ‘any’ になります。
    ‘post’ 投稿
    ‘page’ 固定ページ
    ‘revision’ 履歴 (リビジョン)
    ‘attachmen’ 添付ファイル。WP_Query のデフォルトでは ‘post_status’ が ‘published’ ですが、添付ファイルはデフォルトで ‘post_status’ が ‘inherit’ になっています。そのため ‘post_status’ を明示的に ‘inherit’ か ‘any’ にしなければ、どの添付ファイルも取得できません。(後に出てくる ステータスのパラメータ を見てください)
    ‘pnav_menu_item’ ナビゲーションメニュー項目
    ‘any’ リビジョンと ‘exclude_from_search’ が true にセットされたものを除き、すべてのタイプを含める。
    ‘カスタム投稿タイプ’ 任意のカスタム投稿タイプ名
    ‘post_status’(string / array)
    投稿ステータスを指定します。 デフォルト値は ‘publish’ です。しかしユーザーがログイン中なら、’private’ が追加されます。さらに管理画面のコンテキストでクエリが動作中なら(管理画面または AJAX 呼び出し)、保護状態のステータスも追加されます。デフォルトでは保護状態のステータスは ‘future’, ‘draft’ と ‘pending’ です。
    ‘publish’ 公開された投稿もしくは固定ページ
    ‘pending’ レビュー待ちの投稿
    ‘draft’ 下書きの投稿
    ‘auto-draft’ コンテンツのない、新規作成された投稿
    ‘future’ 予約公開設定された投稿
    ‘private’ ログインしていないユーザーからは見えない投稿
    ‘inherit’ リビジョン
    ‘trash’ ゴミ箱に入った投稿
    ‘any’ ‘trash’ と ‘auto-draft’ を除き、すべてのステータスの投稿

    ■ 記述例

    $args = array(
      'post_type' => array('post','page'),
      'post_status' => 'publish'
    );
    

    投稿・固定ページ

    特定の投稿や固定ページを直接指定する。

    ‘p’(int)
    投稿のID(post ID)を指定
    ‘name’(string)
    投稿のスラッグを指定
    ‘page_id’(int)
    固定ページのIDを指定
    ‘pagename’(string)
    固定ページのスラッグを指定。子ページを表示するには、スラッシュで区切られた親と子のスラッグを指定する。
    ‘post_parent’(int)
    固定ページのIDを指定。子ページを返す。
    ‘post__in’(array)
    投稿IDを配列で複数指定できる
    ‘post__not_in’(array)
    投稿IDを配列で複数指定。指定した投稿を省く。

    ■ 記述例

    $args = array(
      'p' => 10,
      'name' => 'sample',
      'page_id' => 1,
      'pagename' => 'sample',
      'pagename' => 'contact/form', //子ページ
      'post_parent' => 1,
      'post__in' => array(1,5,12),
      'post__not_in' => array(1,5)
    );
    

    並び順

    ループのソート順を指定する。

    ‘order’(‘ASC’ / ‘DESC’)
    昇順(‘ASC’)・降順(‘DESC’)のどちらで並び替えるかを指定(デフォルト値は’DESC’)。
    ‘ASC’ 最低から最高へ昇順 (1, 2, 3), (a, b, c)
    ‘DESC’ 最高から最低へ降順 (3, 2, 1), (c, b, a)
    ‘orderby’(string / array)
    パラメータで指定した項目の値で投稿をソートする。デフォルトは ‘date’。配列で2つ以上のオプションを含めることもできます。
    使用出来る値は以下。
    ‘none’ 順序をつけない
    ‘ID’ 投稿IDで並び替え
    ‘author’ 著者で並び替え
    ‘title’ タイトルで並び替え
    ‘date’ 日付で並び替え(デフォルト)
    ‘modified’ 更新日で並び替え
    ‘parent’ 投稿/固定ページの親ID順で並び替え
    ‘rand’ ランダムで並び替え
    ‘comment_count’ コメント数で並び替え
    ‘menu_order’ 固定ページの表示順で並び替え。
    固定ページと添付ファイル(ギャラリー内のメディアの順番に相当)で使うことが最も多い。バラバラの値が入った ‘menu_order’ を持つ任意の投稿タイプに対しても使うことができる(デフォルト値は 0)。
    ‘meta_value’ カスタムフィールドで並び替え。’meta_key=keyname’ がクエリに存在しなければいけません。
    ソート順は文字列順になることに注意。
    ‘meta_value_num” カスタムフィールドを数値で並び替え。’meta_key=keyname’ がクエリに存在しなければいけません。
    ‘post__in’ ‘post__in’パラメータの配列に並んだ投稿 ID の順に並び替え

    ■ 記述例

    $args = array(
      'order' => ASC,
      'orderby' => 'ID'
    );
    

    ページ送り

    ページャーに関するパラメータを指定する。

    ‘posts_per_page’(int)
    1ページに含める投稿数。’posts_per_page’=>-1 を使用するとすべての投稿を含めます(このとき ‘offset’ パラメータは無視されます)。ページ送りを使用しない場合でもこのパラメータは使える。ページ送りを使用する場合はこのパラメータと一緒に ‘paged’ パラメータを指定。
    ‘posts_per_archive_page’(int)
    1ページに含める投稿数ですが、アーカイブページ専用です。is_archive() か is_search() が true になるページでは、posts_per_page と showposts の値を上書きします。
    ‘paged’(int)
    現在のページ番号。基本的に get_query_var(‘paged’) を入れるはず
    ‘offset’(int)
    ずらす(または読み飛ばす)投稿の数。注意:offset パラメータをセットすると paged パラメータを無視します。そのためページ送りされません(ワークアラウンドを見るにはここをクリック /en)。反対に ‘offset’ パラメータは ‘posts_per_page’=>-1 が使われると(すべての投稿を表示)無視されます。
    ‘nopaging’(bool)
    すべての投稿を表示するか、ページ送りを使用するか。デフォルト値は’false’で、ページ送りを使用する。
    ‘page’(int)
    静的フロントページ用のページ番号。静的フロントページのページ X に表示されるであろう投稿を表示します。(よく分からん)
    ‘ignore_sticky_posts’(bool)
    先頭固定表示の投稿を先頭に表示するかどうか。デフォルトは ‘false’ で先頭に表示。’true’ にすると先頭には出てこないが、本来並ぶべき位置には出てくる。

    ‘posts_per_page’はフィードでのクエリの場合、WordPressがオプション ‘posts_per_rss’(RSS/Atom フィードで表示する最新の投稿数)の値でこのパラメータを上書きする。それでも投稿数を設定するには ‘post_limits’ フィルターを使うか、’pre_option_posts_per_rss’ フィルターで -1 を返す。

    ■ 記述例

    //現在のページから投稿を表示するが、もしクエリ変数がセットされていなければ(先頭ページなら)パラメータに1をセット
    $paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;
    
    $args = array(
      'posts_per_page' => 10,
      'posts_per_archive_page' => 20,
      'paged' => $paged,
      'offset' => 3,
      'nopaging' => false,
      'ignore_sticky_posts' => true
    );
    

    ※静的フロントページに指定したページテンプレートにおいて、クエリをページ送りに対応させるには get_query_var( ‘page’ ) を使う(‘paged’ではなく’page’)。クエリ変数 ‘page’ は、クイックタグ をコンテンツに含んでおりページ分割された単一の投稿または固定ページについて、ページ番号を保持します。
    例: $paged = ( get_query_var(‘page’) ) ? get_query_var(‘page’) : 1;

    日付

    日付や時間に関するパラメータを指定する。

    ‘year’(int)
    年 (4桁で指定する。例: 2017)
    ‘monthnum’(int)
    月 (1 から 12)
    ‘w’(int)
    年内の週番号 (0 から 53)。MySQL の WEEK コマンド を使用。 “start_of_week” オプションに依存する。
    ‘day’(int)
    日 (1 から 31)
    ‘hour’(int)
    時 (0 から 23)
    ‘minute’(int)
    分 (0 から 60)
    ‘second’(int)
    秒 (0 から 60)
    ‘m’(int)
    年と月で指定。(例: 201706)

    ■ 記述例

    $args = array(
      'year' => 2017,
      'mouthnum' => 6,
      'day' => 14,
      'hour' => 20,
      'minute' => 0,
      'second' => 0,
      'm' => 201706
    );

    さらに複雑な指定ができるdate_queryに関しては「その他」でまとめています

    カテゴリ・タグ・タクソノミー

    カテゴリ

    カテゴリに関するパラメータを指定する。

    ‘cat’(int)
    カテゴリIDを指定(マイナス(-)で省く)
    ‘category_name’(string)
    カテゴリスラッグを指定
    ‘category__and’(array)
    カテゴリIDの配列で指定。指定したIDをすべて含む投稿。
    ‘category__in’(array)
    カテゴリIDの配列で指定。指定したIDのいずれかを含む投稿。
    ‘category__not_in’(array)
    カテゴリIDの配列で指定。指定したIDのカテゴリは省く。

    ■ 記述例

    $args = array(
      'cat' => 5,
      'category_name' => 'info', 'code',
      'category__and' => array( 1, 6 ), //1かつ6
      'category__in' => array( 1, 6 ), //1または6
      'category__not_in' => array( 2, 4 ) //2,4以外
    );
    

    タグ

    タグに関するパラメータを指定する。

    ‘tag_id’(int)
    IDを指定(マイナス(-)で省く)
    ‘tag’(string)
    スラッグを指定
    ‘tag__and’(array)
    タグIDの配列で指定。指定したIDをすべて含む投稿。
    ‘tag__in’(array)
    タグIDの配列で指定。指定したIDのいずれかを含む投稿。
    ‘tag__not_in’(array)
    タグIDの配列で指定。指定したIDのカテゴリは省く。
    ‘tag_slug__and’(array)
    タグスラッグの配列で指定。指定したスラッグをすべて含む投稿。
    ‘tag_slug__in’(array)
    タグスラッグの配列で指定。指定したスラッグのいずれかを含む投稿。

    ■ 記述例

    $args = array(
      'tag_id' => 5,
      'tag' => 'html', 'css',
      'tag__and' => array( 1, 6 ),
      'tag__in' => array( 1, 6 ),
      'tag__not_in' => array( 1, 6 ),
      'tag_slug__and'=> array( 'html', 'css' ),
      'tag_slug__in'=> array( 'html', 'css' )
    );
    

    タクソノミー

    タクソノミーに関するパラメータを指定する。

    ‘tax_query’(array)
    タクソノミーに関する引数をまとめる配列
    array( array( ‘taxonomy’ ))(string)
    タクソノミー名
    array( array( ‘field’ ))(‘id’ / ‘slug’)
    ID(‘id’)かスラッグ(‘slug’)のどちらでタクソノミーを指定するかを宣言しておく。
    array( array( ‘terms’ ))(int / string / array)
    タームのIDまたはスラッグを指定(‘field’で宣言した方)。複数指定の場合は配列で。
    array( array( ‘operator’ ))(‘AND’ / ‘IN’ / ‘NOT IN’)
    ‘terms’が配列のとき、全て含む(‘AND’)、いずれかを含む(‘IN’)、省く(‘NOT IN’)を指定できる
    array( array( ‘include_children’ ))(bool)
    階層構造を持っている場合、子タクソノミーを含めるかどうか。デフォルトはtrue。
    array( ‘relation’ )(‘AND’ / ‘OR’)
    これらをそれぞれを複数指定する場合に、すべてを含む(AND)ものか、いずれかを含む(OR)ものかを指定。
    配列の最初で指定する例がほとんどだが、最後でもOK。

    ■ 記述例

    $args = array(
      'tax_query' => array(
        'relation' => 'AND', 
         array(
            'taxonomy' => 'movie',
            'field' => 'id',
            'terms' => array( 102, 114, 235 ),
            'include_children' => false,
            'operator' => 'NOT IN'
         ),
         array(
            'taxonomy' => 'movie',
            'field' => 'slug',
            'terms' => array( 'action', 'comedy' ),
            'include_children' => true,
            'operator' => 'IN'
         ),
         //'relation'はここでもいい
        )
    );
    

    カスタムフィールド

    カスタムフィールドに関する指定は2パターンある。

    keyやvalueを一つずつ指定する単純なパターン

    パターン1。keyとvalueを一つずつ引数に指定する。

    ‘meta_key’(string)
    カスタムフィールドのキー。
    ‘meta_value’(string)
    カスタムフィールドの値(文字列として比較)。
    ‘meta_value_num’(number)
    カスタムフィールドの値(数値として比較)。
    ‘meta_compare’(string)
    ‘meta_value’のテスト演算子。 使える値は以下。
    データ型 意味 有効なデータ型
    ‘=’ 値と一致する すべて(省略時)
    ‘!=’ 値と一致しない すべて
    ‘>’ 値より大きい 数値系・日時系
    ‘>=’ 値以上 数値系・日時系
    ‘<‘ 値より小さい 数値系・日時系
    ‘<=’ 値以下 数値系・日時系
    ‘LIKE’

    値で指定した文字列に一致する
    (※SQLの「%○○%」と同じ)

    ‘CHAR’
    ‘NOT LIKE’ 値で指定した文字列に一致しない CHAR
    ‘IN’ 値(配列)で指定した何れかに一致する すべて
    ‘NOT IN’ 値(配列)で指定した何れにも一致しない すべて
    ‘BETWEEN’ 2つの値で指定した範囲内(○以上○以下) 数値系・日時系
    ‘NOT BETWEEN’ 2つの値で指定した範囲外 数値系・日時系

    ■ 記述例

    //meta_valueが文字列の場合
    $args = array(
      'meta_key' => 'color',
      'meta_value' => 'red',
      'meta_compare' => '=',
      )
    
    //meta_valueが数値の場合
    $args = array(
      'meta_key' => 'number',
      'meta_value_num' => 10,
      'meta_compare' => '=',
      )
    

    keyやvalueを複数指定するパターン

    パターン2。配列の中に情報を入れてカスタムフィールドに関するパラメータを指定する。

    ‘meta_query’(array)
    カスタムフィールドパラメーター。この配列に情報を入れていく。
    array( ‘relation’ )(‘AND’ / ‘OR’)
    meta_query の中に複数の配列を入れたときの論理値関係。使える値は ‘AND’ と ‘OR’ (デフォルトは’AND’)。
    ※ひとつだけ配列を入れるときは使わない。
    array( array( ‘key’ )(string)
    カスタムフィールドのキー。
    a->( a->( ‘value’ ))(string / array)
    カスタムフィールドの値。配列を指定できるのは compare が ‘IN’, ‘NOT IN’, ‘BETWEEN’ または ‘NOT BETWEEN’ の場合のみ。
    WordPress 3.9 からは compare に ‘EXISTS’ または ‘NOT EXISTS’ を指定する場合は value を省略できるようになった。
    a->( a->( ‘type’ ))(string)
    カスタムフィールドの値のタイプ。使える値は以下。
    データ型 意味
    ‘CHAR’ 文字
    ‘NUMERIC’ SIGNEDの別名
    ‘DECIMAL’ 浮動小数点数
    ‘SIGNED’ 整数(符号あり)
    ‘UNSIGNED’ 整数(符号なし)
    ‘DATE’ 日付
    ‘DATETIME’ 日時
    ‘TIME’ 時刻
    ‘BINARY’ バイナリー
    array( array( ‘compare’ )(string)
    テスト演算子。使える値はパターン1の’meta_compare’と同じです。

    ■ 記述例

    $args = array(
      'meta_query' => array(
        'relation' => 'OR',
        array(
          'key' => 'color',
          'value' => 'red',
          'type' => 'CHAR',
          'compare' => '='
        ),
        array(
          'relation' => 'AND',
          array(
            'key' => 'price',
            'value' => array( 100, 200 ),
            'compare' => 'IN'
          ),
          array(
            'key' => 'size',
            'value' => 'big',
            'compare' => 'IN'
          )
        )
      )
    );
    

    この記述例のようにarrayを入れ子にした使い方もできます。カスタムフィールドの指定は自由度が高く複雑なので、別のページで様々な例をまとめてみましたので、そちらも参考にしてみてください。

    その他 (あんま使わんやつ)

    日付をさらに詳細指定(date_query)

    日付や日時に関するパラメータをを配列に入れてさらに詳細に指定する。

    ‘date_query’(array)
    複雑な指定ができる日付パラメータ
    a->( ‘year’ )(int)
    月 (1 から 12)
    a->( ‘monthnum’ )(int)
    月 (1 から 12)
    array( ‘w’ )(int)
    週番号 (0 から 53)
    array( ‘day’ )(int)
    日 (1 から 31)
    array( ‘hour’ )(int)
    時 (0 から 23)
    array( ‘minute’ )(int)
    分 (0 から 60)
    array( ‘second’ )(int)
    秒 (0 から 60)
    array( ‘after’ )(string / array)
    この日付より後の投稿を取得。strtotime() 互換の文字列、または ‘year’, ‘month’, ‘day’ の値を持つ配列を指定可能
    array( ‘before’ )(string / array)
    この日付より前の投稿を取得。strtotime() 互換の文字列、または ‘year’, ‘month’, ‘day’ の値を持つ配列を指定可能
    array( ‘inclusive’ )(bool)
    after と before について、指定された日付ぴったりを含めるかどうか。
    array( ‘compare’ )(string)
    参考: WP_Date_Query::get_compare() を見てください。
    array( ‘colum’ )(string)
    クエリ対象とする(wp_posts テーブルの)カラム。デフォルトは ‘post_date’。
    array( ‘relation’ )(‘OR’ / ‘AND’)
    子の配列をどのように結合して比較するか。デフォルトは AND(かつ)。

    投稿者

    ユーザーに関連付けられた投稿を指定する。

    ‘author’(int)
    ユーザーID ( – で省く)
    ‘author_name’(string)
    ユーザ名( user_nicename )。性・名・ニックネームではない
    ‘author__in’(array)
    ユーザーIDで指定。複数を指定できる。
    ‘author__not_in’(array)
    ユーザーIDで指定。指定した投稿者を省く

    パスワード

    バージョン 3.9 からパスワードの状態を指定できるようになっています。

    ‘has_password’(bool)
    パスワードで保護された投稿を表示するには true、保護されてない投稿を表示するには false を指定。パスワードの有無に関わらず表示したい場合は null (デフォルト) を指定。
    ‘post_password’(string)
    特定のパスワードで保護されている投稿を表示。

    検索用

    検索機能に使われるパラメータを指定する

    ‘s’(string)
    検索するキーワードを指定。search.phpなどで使用する。

    権限

    ユーザーが適切な権限を持っていれば、公開済みの投稿と同様に、プライベートの記事を表示します。

    ‘perm’(‘readable’ / ‘editable’)
    ユーザー権限を指定(readableまたはeditable)。

    キャッシュ

    取得したデータがキャッシュへ追加されるのを禁止できる。

    ‘cache_results’(bool)
    投稿情報のキャッシュをどうするか。falseで禁止
    ‘update_post_meta_cache’(bool)
    投稿のメタ情報(カスタムフィールドなど)のキャッシュをどうするか。falseで禁止
    ‘update_post_term_cache’(bool)
    投稿のターム情報(カテゴリなど)のキャッシュをどうするか。falseで禁止

    戻り値

    戻り値を指定する。

    ‘fields’(string)
    どのフィールドを返すか指定。下の二つ以外の何かを指定するとすべてのフィールドを返す(デフォルト)。
    ‘ids’ 投稿IDの配列を返す
    ‘id=>parent’ プロパティに ID(投稿ID)と post_parent(親のID)を持つ stdClass オブジェクトの配列を返す

    おまけ

    ループ内で使用する主要な情報

    ループ内でよく使うであろう、記事タイトルや投稿日などはまとめて変数に入れて使用すると便利です。

    //ループ上部で先に記述しておくと便利
    
    $title    = esc_html(get_the_title()); //投稿タイトル
    $url      = esc_url(get_permalink());  //投稿のurl
    $date     = get_the_time('Y/m/d'); //投稿日
    $modify    = get_the_modified_date('Y/m/d'); //更新日
    $category = get_the_category();    //カテゴリ情報
    $tags     = get_the_tags();        //タグ情報
    $content  = mb_substr(esc_html(get_the_content()),0,60)."..."; //本文
    
    //アイキャッチ画像のurlを取得しておく
    if(has_post_thumbnail()):
      $src = get_thumb_src('サイズ');
    else:
      $src = "デフォルト画像へのパス";
    endif;
    

    アイキャッチ画像の部分でのget_thumb_src()という関数は下の記事で紹介した関数です。

    ページャーを使用する時の記述例(WP_pagenaviを使用した場合)

    //現在のページを教える
    $paged = get_query_var('paged')? get_query_var('paged') : 1;
    $args = array(
    
      //引数...
    
      'paged' => $paged,
    );
    
    $the_query = new WP_Query($args);
    if ($the_query->have_posts()) :
      while ($the_query->have_posts()) : $the_query->the_post();
    
        //ループ
    
      endwhile;
    endif;
    //wp_pagenaviの記述
     wp_pagenavi(array('query'=>$the_query));
     wp_reset_postdata();
    - Thank you for reading this to the end. -

    コメントする

    CAPTCHA


    TOPへ Top