2016/10/02 12:45:00

wordpressのWP_Queryクラスが取る引数をまとめてみた

目次(クリックするとジャンプします)
  • 1:WP_Queryクラスのコンストラクタ引数
  • 2:パラメータまとめ表
  • 3:補足説明
  • 3.1:パラメータの多さ
  • 3.2:良く分からないパラメータ
  • 4:まとめ

WP_Queryクラスのコンストラクタ引数

wordpressカスタマイズにおいてWP_Queryクラスをnewしてインスタンスを得る場合があるかとおもいますが、コンストラクタが取る引数のパラメータが膨大で、値の設定に苦労されている人も多いのではないかと思います。@MINOがまさにその状態です。

今回奮起してパラメータを調べてみようと思い、WP_Queryクラスが定義されているwp-includes内にあるquery.phpを覗いてみました。 @MINOの力量だとソースを読むのはなかなか骨が折れますが、一応パラメータリストを作る事は出来きました。

ただ@MINOの英語力も最悪なのでうまく訳せていない箇所もあるし、そのパラメータがどのように動作するかが判らなかったものもあります。 その為完全なリストとは全く言えません。

参考程度にはなるかと思うのであまり期待しないで閲覧してもらえると幸いです。

パラメータまとめ表

パラメータはアルファベット順にしてあります。

クエリ 意味 値の型 初期値 許可される値
attachment_id 添付ファイルのポストID int
author 著者ID、または著者IDのカンマ区切りのリスト int|string
author_name 著者のニックネーム string
author__in 著者IDの配列 array
author__not_in 著者IDの配列(NOT) array
cache_results 投稿情報をキャッシュするかどうか bool ture
cat カテゴリIDまたはIDのカンマ区切りのリスト(または子カテゴリ) int|string
category__and カテゴリIDの配列(AND) array
category__in カテゴリIDの配列(OR 子カテゴリなし array
category__not_in カテゴリIDの配列(NOT) array
category_name カテゴリスラッグ string
comments_per_page ページごとのコメント数 int
comments_popup クエリは、コメントのポップアップ内にあるかどうか? int|string empty
date_query WP_Date_Query用の引数の連想配列 array
day int empty 1~31
exact 正確なキーワードで検索するか bool ture
fields フィールド一つで返すか配列で返す string|array all fields ids’, ‘id=>parent’.
hour 時間 int 0~23
ignore_sticky_posts 「この投稿を先頭に固定表示」を無視するか(false) bool 0|false. 1|true, 0|false.
m 任意の4桁の年と月を受け入れ int empty 西暦4桁+1~12
meta_compare 「meta_value」をテストするための比較演算子 string
meta_key カスタムフィールドキー string
meta_query WP_Meta_Query用の引数(連想配列) array
meta_value カスタムフィールドの値 string
meta_value_num カスタムフィールド値番号? int
menu_order 投稿のメニューの順番? int
monthnum int empty 1~12
name 投稿のスラッグ string
nopaging すべての投稿を表示か(ture)、ページ分割するか(false) bool false
no_found_rows カウントをスキップする?tureでパフォーマンスが向上する可能性がある? bool false
offset オフセット int
order 結果表示のソート 昇順または降順指定 string DESC’ ‘ASC’, ‘DESC’.
orderby 結果表示のソート 複数のオプションが可能 string date’ ‘none’, ‘name’, ‘author’, ‘date’, ‘title’, ‘modified’,’menu_order’, ‘parent’, ‘ID’, ‘rand’, ‘comment_count’
p 投稿のID int
page 静的なフロントページのページXに表示される投稿数を表示 int
paged 現在のページの数 int
page_id 固定ページのID int
pagename 固定ページのスラッグ string
perm ユーザーの権限による投稿表示抑制 string
post__in 取得する投稿IDの配列、スティッキーポストを含む array
post_mime_type 投稿のMIMEタイプ string
post__not_in 除外する投稿IDの配列(カンマで区切りは無効) array
post_parent 子ページを取得するためのページID トップレベルの取得には0を指定 int
post_parent__in 子ページを照会する親ページIDを含む配列 array
post_parent__not_in 除外する子ページ、親ページのIDを含む配列 array
post_type 投稿タイプのスラッグ(文字列)または投稿タイプのスラッグの配列 string
post_status 投稿の状態(文字列)または状態の配列 string publish’,’pending’,’draft’,’auto-draft’,’future’,’private’,’inherit’,’trash’,’any’
posts_per_page 照会する投稿の数。 -1指定ですべての投稿を取得する int
posts_per_archive_page 検索ページまたはアーカイブページにおいて照会する投稿の数 int
s 検索キーワード string
second int 0~60
search_terms タームの配列 array
sentence 語句で検索するか bool false
suppress_filters フィルターを非表示にするかどうか bool false
tag タグスラッグ。カンマ区切り(いずれか)、プラスで区切られた(すべて) string
tag__and タグIDの配列(AND) array
tag__in タグIDの配列(OR) array
tag__not_in タグIDの配列(NOT) array
tag_id タグIDまたはIDのカンマ区切りのリスト int
tag_slug__and タグスラッグの配列(AND) array
tag_slug__in タグスラッグの配列(OR)(カンマ区切り無効) 「ignore_sticky_posts」しない限り、真実である? array
tax_query WP_Tax_Query用の引数(連想配列) array
update_post_meta_cache 投稿メタキャッシュを更新するかどうか bool ture
update_post_term_cache 投稿タームキャッシュを更新するかどうか bool ture
w int 0~53
year int 西暦4桁

補足説明

パラメータの多さ

パラメータはなんと66個もあります。これを使いこなせたら相当複雑なクエリを発行することが可能になりますね。機能の設定パラメータも複数あるので、検索値として使えるのは66個よりは少なくなりますが、それでも組み合わせは膨大です。

例えば2014年中に公開、’パソコン’カテゴリに属していて、著者のニックネームが’物書き’の投稿というSQLで書くにはすこし複雑な条件でも

array( 'year' => 2014, 'cat' => 'パソコン', 'author_name' => '物書き' )

で照会することができます。

表示順もデフォルトでは公開日時の降順になっていますが、ID順、コメント数順、タイトル順(辞書順だと思われる)、更新日順、スラッグ順(辞書順だと思われる)、著者順、ランダム順などなど(それぞれの降順、昇順)多彩に設定できる。

良く分からないパラメータ

良く分からなかった、うまく訳せなかったパラメータは「?」を付けています。該当するのはcomments_popup、meta_value_num、menu_order、no_found_rows、tag_slug__inの5つです。

comments_popupはコメントをホップアップさせる機能と関連していると思うのですが、このパラメータの説明である原文「Whether the query is within the comments popup」の意味が分かりませんでした。訳すと「クエリがcomments_popupの中にあるかどうか」といったような意味になると思うのですが、何のことなのかさっぱり。

meta_value_numはおそらくカスタムフィールドに関係すると思います。カスタムフィールドはwp_postmetaというテーブルに格納されており、meta_idという値を持っています。このmeta_idがmeta_value_numのことなんじゃないかと思ったのですが、違うみたいです。指定する値の型はintなので数字になるはずですが…。

menu_orderはおそらく固定ページの表示順の設置に関していると思います(未検証)。

no_found_rowsは英語原文の説明を見る限り、データベースに問い合わせする際の挙動の設定のようです。照会されたrowに対してカウントを行わない的な内容が書かれているのですが、なんのカウントなのかが判らなかったです。またこの設定をtureにするとパフォーマンスが向上する可能性があるとも書かれていました。

tag_slug__inはタグのスラッグの事を指しているのはわかるのですが、英語原文の「unless ‘ignore_sticky_posts’ is true」の注釈の意味が良く分かりませんでした。なぜ’ignore_sticky_posts’と関係あるのでしょう?

以上はあまり使わなさそうなパラメータだが、判らず釈然としません。申し訳ないです。

まとめ

WP_Queryクラスはとても便利。データベースに問い合わせする仕組みとして、wordpressでは$wpdbインスタンスを用意してくれているが、これはガチのSQLクエリが必要になるので慣れていない人は大変だろうと思います。

WP_Queryクラスなら、適切にパラメータを設定してあげるだけで、インスタンスを得ることができます。

$wpdbインスタンスは最後の手段としておいて、WP_Queryクラスを使いこなせるようになるのが良いのではないかと思います。

ともすれば$wpdbインスタンスで何とかしようとするのは、@MINOの悪い癖です。