関数リファレンス/WP Query

WP_Queryの役割

WP_Queryはwp-includes/query.phpに定義されているクラスで、WordPressブログへの複雑なリクエストを取り扱います。wp-blog-header.php(バージョン2.0ではWPクラス)が$wp_queryオブジェクトに現在のリクエストを定義する情報を与えることで、$wp_queryは扱うべきはどのタイプのクエリなのか(カテゴリーアーカイブ？ 年月別アーカイブ？ フィード？ 検索？)ということを理解し、要求された投稿を取り出します。$wp_queryはリクエスト上の情報を多く保持していて、後からでも利用することができます。

メソッドとプロパティ

これはWP_Queryの公式な文書です。プロパティを直接書き換えるべきではありません。その代わりにメソッドを使って操作することができます。クラスのメンバとグローバル変数がしっちゃかめっちゃかになることを避ける便利な関数がありますので、WP_Queryに働きかけるを参考にしてください。

プロパティ

$query

wp-blog-header.php(バージョン2.0ではWPクラス)によって$wp_queryオブジェクトに渡されるクエリ文字列。このクエリ文字列の構造については、WordPress Code Flowを見てください(WP1.5のwp-blog-header.phpに関するもの - この情報は古くなっています)。

$query_vars

$query解析されたから成る連想配列:クエリ変数の配列とそれぞれの値。

$queried_object

リクエストがカテゴリー、作者ページ、パーマリンク、ページだった場合に適用される。

$queried_object_id

上記のプロパティのIDを持つ。

$posts

要求された投稿をデータベースから取得したもの。

$post_count

表示される投稿の数。

$current_post

(ループ内でのみ使用可能)表示されようとしている投稿の数。

$post

(ループ内でのみ使用可能) 今表示されている投稿。

$is_single, $is_page, $is_archive, $is_preview, $is_date, $is_year, $is_month, $is_time, $is_author, $is_category, $is_tag, $is_tax, $is_search, $is_feed, $is_comment_feed, $is_trackback, $is_home, $is_404, $is_comments_popup, $is_admin, $is_attachment, $is_singular, $is_robots, $is_posts_page, $is_paged

ブーリアンリクエストがどのタイプなのかを判断する。最初の三つを例に取れば、'これはパーマリンクか？'、'これはページか？'、'これはなんらかのアーカイブページか？'となる。

メソッド

(メソッド名の前にあるアンパサンド(&)はそれが参照渡しであることを示します。)

init()

オブジェクトを初期化して、すべてのプロパティをnull、ゼロ、falseにセットする。

parse_query($query)

リクエストを定義するクエリ文字列を受け取り、それを解析して$posts、$post_count、$post、$current_post以外のすべてのプロパティを返す。

parse_query_vars()

古いクエリ文字列をもう一度解析する。

get($query_var)

指定されたクエリ変数を取得する。

set($query_var, $value)

指定されたクエリ変数を任意の値に設定する。

&get_posts()

要求された投稿をデータベースから取得して返す。$postsと$post_countも返す。

next_post()

(ループ内でのみ使用可能)$postsで次の投稿に進む。$current_postを1つ増やし、$postを設定する。

the_post()

(ループ内でのみ使用可能)次の投稿に進み、グローバル変数$postを設定する。

have_posts()

(ループ内か、ループの前でのみ使用可能) 表示する投稿が残っているかを示す。

rewind_posts()

$current_postと$postをリセットする。

&query($query)

parse_query()とget_posts()を呼び出し、get_posts()の結果を返す。

get_queried_object()

$queried_objectを設定し、それがまだ設定されていなければ、返す。

get_queried_object_id()

$queried_object_idを設定し、それがまだ設定されていなければ返す。

WP_Query($query = '') (コンストラクタ)

クエリ文字列を与えれば、それを使ってquery()を呼び出す。

WP_Queryに働きかける

ほとんどの場合、クラスの内部やグローバル変数を使わなくても欲しい情報は手に入れられるでしょう。どこからでも欲しい情報を手に入れるために、厖大な数の関数があるのですから。

WP_Queryを使いたくなるかもしれないケースが二つあります。一つは、WordPressが今扱っているリクエストがどんなものかを知るためです。$is_*プロパティはこの情報を持つよう設計されています: このためには条件分岐タグを使ってください。これはプラグイン作者(そして、テーマ作者)によくあるケースです。

二つ目はループの中です。WP_Queryはループ内において、よくある要望を実現するための厖大な関数を備えています。たとえば$wp_query->have_posts()を呼び出すhave_posts()は、表示すべき投稿があるかどうかを判断するために呼び出されます。whileループの開始時に、have_posts()を条件として使います。このループは表示すべき投稿がある限り反復されます。反復処理を行うごとに、$wp_query->the_post()を呼び出すthe_post()が呼び出され、$wp_query内の変数とグローバル変数$post(テンプレートタグはこれに依存します)をセットします。これは上で見た通りです。ループを必要とするテーマを作っている時、使うべき関数はたくさんあります。詳しくはループとThe Loop in Actione:The Loop in Actionを見てください。