get_posts() の使い方｜説明・引数・注意点

説明

基本構文

get_posts( array $args = null ): WP_Post[]|int[]

引数

• $args：取得条件の配列。numberposts、category、post_type、orderby、order、meta_key など

戻り値

WP_Post オブジェクトの配列。fields => 'ids' のときはIDの配列。

使い方（サンプル）

$posts = get_posts( array(
	'post_type'   => 'post',
	'numberposts' => 5,
	'orderby'     => 'date',
	'order'       => 'DESC',
) );
foreach ( $posts as $post ) {
	echo esc_html( $post->post_title );
}

注意点

• numberposts の既定値は5件です。全件取得は -1 を指定しますが、件数が多いとメモリを圧迫します。
• ループ内のグローバル $post は更新されないため、テンプレートタグを使う場合は setup_postdata() が必要です。
• ページネーションが必要な場合は WP_Query を使います。
• suppress_filters が既定で true のため、一部のフィルターが効きません。

実務での使いどころ

• フロントページや固定ページに、「最新のお知らせ3件」のような別枠の一覧を出すとき（ページ送りが不要なとき）。
• 投稿IDの配列だけが欲しいとき。'fields' => 'ids' を指定すると、IDだけを取得できます。
• 関連記事や、おすすめ記事の取得。

よくあるミスと対処

• numberposts を指定せず、5件しか出ない。get_posts() の既定の取得件数は5件です。
• ループ内で the_title() などのテンプレートタグを使う前に、setup_postdata() を呼んでいない（関数の中で使う場合は、global $post; の宣言も必要です）。現在のページの情報が出てしまいます。
• メインクエリの一覧を変えるために使っている。get_posts() は別のクエリなので、メインの一覧には影響しません（変更したいときは pre_get_posts フックを使います）。なお、pre_get_posts は get_posts() の内部クエリでも実行されるため、フック側では is_main_query() の判定が必要です。

NG例

$posts = get_posts( array( 'post_type' => 'news', 'numberposts' => 3 ) );
foreach ( $posts as $post ) {
	the_title(); // 現在のページのタイトルが出てしまう
}

OK例

global $post; // 関数の中で使う場合に必要

foreach ( $posts as $post ) {
	setup_postdata( $post );
	the_title();
}
wp_reset_postdata();

使い分け早見表

関連項目

WP_Query、get_post()、wp_get_recent_posts()、setup_postdata()、wp_reset_postdata()

公式リファレンス：get_posts() | Function | WordPress Developer Resources