【WordPress】WP_Queryの一番簡単な使い方

2022.10.06 更新

2,250views

PHP WordPress プログラミング

WordPressではトップページ、一覧ページ、サイドバーとあらゆるところで「ループ機能」というものを使います。ループ機能を使うと様々な条件で記事を取得することができます。

今回はループ機能を使う上で、最も汎用性が高いWordPress関数である「WP_Query()」メソッドの一番簡単な使い方を書いていきます。

WP_Queryの仕組み
単純なループを紹介
よく使う情報を表示する関数一覧

WP_Queryの仕組み

WP_Queryはwp-includes/class-wp-query.phpに定義されているクラスです。返値に指定した条件の記事データ配列を取得することができます。WP_Queryの引数をカスタマイズすることで、WordPress内で保有している記事の様々な情報を取得したり、取得したい情報保有している記事をソートしてループをリクエストすることができます。

取得した記事の情報は記事のアイキャッチ・タイトル・公開日・更新日などの基本情報や、独自に設定したカスタムフィールド（Ex.閲覧数）とその記事の全ての情報にアクセスできます。

ループ後に記事情報をリセットするwp_reset_postdata関数を実行することでループ中に取得した情報はメインのループに依存させなくし、メインクエリが現在表示している投稿の情報取得を邪魔しない状態にします。WP_Queryクラスを宣言したら必ず最後にwp_reset_postdata関数を実行してください。

単純なループを紹介

WP_Queryはまず引数を指定しながらクラスを宣言することで使うことができます。ここで

投稿タイプ：投稿

最大ループ：5回

の条件でのループ例を紹介します。ループ中に使用する関数は下で紹介しています。

<?php
$args = array(
  'post_type' => 'post',
  'posts_per_page' => 5
);
$posts = new WP_Query( $args );
if($posts->have_posts()):
  while($posts->have_posts()):
    $posts->the_post();
    the_title('<h2>','</h2>');
    the_date('Y/m/d'); ?>
    <a href="<?php the_permalink(); ?>">
    <?php the_post_thumbnail('full'); ?>
    </a>
<?php
    the_excerpt();
  endwhile;
  wp_reset_postdata();
else:
  echo '投稿はありませんでした。';
endif;
?>

このコードを試しに埋め込むと、タイトルと投稿日、リンク付きサムネイル、抜粋が投稿の新しい順に5つ表示するループが生成されます。

様々なパラメータの情報は、また別の記事で紹介します。

よく使う情報を表示する関数一覧

WP_Queryを使うとき、タイトルやサムネイルなどを取得・表示する関数をまとめます。

情報を表示する「the_〇〇()」にはtheの前にgetをつけた「get_the_〇〇()」が存在する場合が多いです。get_the_○○の場合は〇〇の情報が返り値として渡され、the_〇〇の場合は、HTMLとして表示されます。

記事タイトル

取得した投稿のタイトルの表示方法は2通りあります。

<?php the_title( $before,$after,$echo ); ?>

$before,$afterはタイトルの前後にHTMLテキストを挿入したい場合に引数を渡します。デフォルトは''です。
$echoは表示するか返すかを選べます。初期値はTRUEです。

<?php echo esc_html(get_the_title( $ID )); ?>

$IDに投稿のIDを渡すことで特定の記事のタイトルを取得することができます。HTMLとして表示する場合は、エスケープ処理としてesc_html関数を使用してください。

公開日・更新日

公開日と更新日は似た関数なので同時に紹介します。表示する方法は関数実行で表示する方法とechoにより表示する方法の2通りあります。

<?php the_date( $id,$before,$after,$echo ); ?>
<?php the_modified_date( $id,$before,$after,$echo ); ?>

$dは表示する日付フォーマットを渡す引数です。例えば

<?php the_date('Y-m-d'); /* 2020-03-01 */ ?>
<?php the_date('F j, Y'); /* March 1,2020 */ ?>
<?php the_date('y/M/D'); /* 20/Mar/Sun */ ?>

デフォルトは設定のオプションで指定した形式を表示します。

$before,$after,$echoはタイトルと同様なので省略します。

<?php echo get_the_date( $id,$post ); ?>
<?php echo get_the_modified_date( $id,$post ); ?>

引数の説明は同上のため省略します。

こちらは変数に代入することができるので、公開日と更新日が同じか確認することで更新されたことがある投稿かどうかの分岐をすることもできます。

<?php
$public = get_the_date('Y-m-d');
$modify = get_the_modified_date('Y-m-d');
if($public === $modify){
  echo　'投稿は一度も更新されていません！公開日は'.$public.'です。';
}else{
  echo '投稿は'.$modify.'に更新されました。';
}
?>

この分岐を使い、常に更新した最新日時を検索エンジンにクロールさせることでSEO効果を期待した投稿にすることができます。

カテゴリー

投稿にカテゴリーを設定している場合は多いと思います。通常の投稿タイプの場合

<?php the_category( $separator,$parents,$post_id ); ?>

で表示できます。

$separatorは複数カテゴリーがある場合の区切りテキストを設定できる引数です。デフォルトでは<ul>タグでリンクを並べます。

$parentsは子カテゴリーに属している場合の表示方法を設定でき、'multiple'と渡すことで親と子それぞれに別でリンクを表示し、'single'で小カテゴリーのみにリンクを表示することができます。デフォルトでは小カテゴリーへのリンクで親子関係を表示しません。

$post_idで取得する投稿のIDを設定するのでWP_Queryループ内で使用する場合基本的に、$posts->IDと渡します。（$postsはクラス宣言を代入した変数です。）

カスタム投稿タイプでカスタムカテゴリーのみを表示したい場合は

<?php the_terms( $id,$taxonomy,$before,$sep,$after ); ?>

$idに投稿IDを渡し、$taxonomyにカスタムカテゴリーのタクソノミーを渡すことで表示できます。$sepは投稿に複数カテゴリーがある場合の区切りテキストを設定します。

例

<?php the_terms( $posts->ID,'blog-cat','カテゴリー~','/','~' ); ?>

アイキャッチ

<?php the_post_thumbnail( $size,$attr );

$sizeは表示するアイキャッチの大きさを指定できる引数で、既存で('thumbnail','medium','large','full')と指定することで、([150px,150px],[300px,300px],[1024px,1024px],[full,full])になります。

cssで横幅を後から指定することを考えるとあらかじめ大きいサイズに指定しておく方が、画質の面でも都合がいいことも多いです。しかし一覧ページのような多くの記事を表示する場合、全て高画質だと通信量が多くなってしまいますので注意してください。

$attrはアイキャッチを表示する<img>タグの属性値を任意に指定することができる引数です。配列形式で渡します。初期値は

<?php $attr = array(
              'src'   => $src, //アイキャッチが設定されている投稿のURL
              'class' => "attachment-$size",
              'alt'   => trim(strip_tags( $wp_postmeta->_wp_attachment_image_alt))
)?>

となっています。