WP Query Builderの生成コードをWordPressへ安全に貼る方法
｜本番前の7項目

最初に、生成コードだけで完成ではないと確認する

公開中のWP Query Builderで投稿タイプを「通常投稿」、公開状態を「公開済み」、取得件数を3にし、自動高速化をオフ、先頭固定の優先表示を無効（ignore_sticky_posts=true）にすると、次のコードが生成されます。並び順は既定の公開日降順です。

$args = array(    'post_type' => 'post',    'post_status' => 'publish',    'posts_per_page' => 3,    'ignore_sticky_posts' => true);

この配列は「何を取得するか」をWP_Queryへ渡す条件です。生成された配列だけでは、一覧の表示は完成しません。 どのファイルで実行するか、どんなHTMLで表示するか、0件のときに何を見せるかは別に決めます。3件は取得上限なので、該当する公開投稿が少なければ3件未満になります。

ここを分けておくと、「生成できたのに何も表示されない」ときも、取得条件と設置方法を別々に調べられます。先頭固定の優先表示を無効にしないと、条件によっては固定記事が加わり、指定件数や日付順と違う結果になる場合があります。ignore_sticky_posts=trueは固定記事を除外する指定ではなく、通常の投稿として日付順に扱う指定です。

生成コードは、本番と分けたWordPress環境で表示処理と組み合わせて試します。検証用や公開用のサーバーをこれから用意する場合は、XserverのPHP対応やバックアップ条件も確認できます。

本番へ貼る前に確認する7項目

上から順に進めると、確認漏れを減らせます。

1. コピーした範囲が$argsだけか確認する

まず、コピーしたコードの先頭と末尾を見ます。$args = array(から始まり);で終わるなら、取得条件だけです。$args = [から始まり];で終わる書き方も配列を表します。new WP_Query()、have_posts()、the_post()がなければ、投稿を取得・表示する処理を別に用意する必要があります。

逆に、すでにテンプレート側にループがあり、$argsだけを差し替える設計なら、同じループを二重に追加しません。どこまで用意済みかを確認してから編集範囲を決めます。

2. コードを置く場所を、やりたいことから決める

PHPコードは、WordPressの固定ページ本文やCSS欄へ貼るものではありません。追加の投稿一覧を表示するなら、クラシックテーマでは子テーマのテンプレートやテンプレートパーツが候補です。ブロックで実現できるなら、先にQuery Loopを検討します。

設置場所をまだ決められない場合は、コードを貼る前に確認しましょう。取得条件が正しくても、置く場所が違えば、意図した場所で意図したとおりには動きません。

3. 親テーマではなく、子テーマかサイト固有プラグインを使う

親テーマのファイルへ直接書くと、テーマ更新で変更が消える可能性があります。WordPress公式のChild Themesでは、子テーマにカスタマイズを分離することで、親テーマを更新しても変更を保ちやすいと説明されています。

表示がテーマに属するなら子テーマ、テーマを替えても残す取得処理や機能ならサイト固有プラグイン、という基準で分けます。「PHPならすべてfunctions.php」ではありません。

4. バックアップを取るだけでなく、戻し方まで確認する

WordPressサイトは、ファイルとデータベースに分かれています。テーマファイルのバックアップだけでは、投稿、設定、メニュー等のデータベース内容まで戻せません。逆に、データベースだけではテーマやプラグインのファイルを戻せません。

バックアップが作成済みでも、保存場所や復元手順が分からなければ緊急時に使えません。少なくとも、変更ファイルを1つ前へ戻す方法と、サイト全体を復元する担当・手順を作業前に確認します。テーマのコードだけを変更した場合は、まず変更ファイルだけを戻します。 データベース全体を古い状態へ戻すと、その後の投稿・注文・問い合わせなども失われるおそれがあるため、別の判断が必要です。

5. 自分の値へ差し替え、表示ループを完成させる

生成コードにあるpost_type、カテゴリーやタグのスラッグ、投稿ID、メタキーは、実際のWordPressに存在する値と一致させます。サンプルのnewsやevent_dateをそのまま使っても、同じ投稿タイプや保存値がなければ、期待する投稿を取得できません。

ページの途中に新着一覧を追加する場合は、生成した$argsに取得・表示・0件時・リセットの処理を手動で組み合わせます。以下をクラシックテーマの子テーマにあるtemplate-parts/latest-posts.phpとして保存します。新規PHPファイル全体の例なので、先頭の<?phpを含めています。

<?php$args = [   'post_type'      => 'post',   'post_status'    => 'publish',   'posts_per_page' => 3,   'orderby'        => 'date',   'order'          => 'DESC',   'ignore_sticky_posts' => true,]; $latest_posts = new WP_Query( $args ); if ( $latest_posts->have_posts() ) {   echo '<ul class="latest-posts">';    while ( $latest_posts->have_posts() ) {      $latest_posts->the_post();      printf(         '<li><a href="%1$s">%2$s</a></li>',         esc_url( get_permalink() ),         esc_html( get_the_title() )      );   }    echo '</ul>';} else {   echo '<p>表示できる記事はありません。</p>';} wp_reset_postdata();

この完成例では、生成された配列を[]表記に整え、既定の並び順をorderbyとorderで明記しています。esc_url()とesc_html()は、リンク先とタイトルをそれぞれの出力先に合わせてエスケープする処理です。the_post()を使った追加ループの後は、wp_reset_postdata()でメインクエリの投稿情報へ戻します。別の独自ループの内側へ入れる例ではありません。

パーツを保存するだけでは表示されません。固定ページの本文の後に置くなら、子テーマ側で実際に使われるpage.phpのメインループ内で、the_content()の後へ次の呼び出しを追加します。ファイル全体を置き換えず、既存のヘッダー・フッターやメインループを残してください。すでにPHPが開いている位置では、<?phpと?>を重ねず呼び出しの行だけを追加します。

<?php get_template_part( 'template-parts/latest-posts' ); ?>

get_template_part()には.phpを付けません。ここまでの表示処理をfunctions.phpへそのまま貼ると、表示したい位置で動くとは限りません。基本構文を1行ずつ見直したい場合は、WP_Queryの基本構文と$argsの書き方を確認してください。

条件が違っていた場合は、手作業で直す行を増やす前に、WP Query Builderで投稿タイプ、公開状態、件数、並び順を設定し直します。画面の入力と日本語の説明が同じ内容になっていることを確かめてから、コードを置き換えてください。

表示パーツと呼び出し元が分かったら、WP Query Builderで自分のサイトの取得条件を作り直せます。完成例の配列部分だけを置き換え、ループとリセットを残して検証してください。

6. PHPの構文を、本番に近いバージョンで検査する

PHPのコマンドラインには、コードを実行せず構文だけを検査する-lがあります。WordPressを設置したフォルダーで、子テーマのパーツと呼び出し元の両方を検査します。my-childは実際のフォルダー名に置き換えてください。

php -l wp-content/themes/my-child/template-parts/latest-posts.phpphp -l wp-content/themes/my-child/page.php

No syntax errors detectedと表示されれば、括弧やセミコロンなどの構文は通っています。ただし、投稿タイプのスラッグが正しいか、WordPress関数を適切な場所で呼んでいるか、表示結果が意図どおりかまでは判定しません。

7. ローカルとステージングで、成功と失敗の両方を試す

最初はローカル環境に該当する公開投稿を3件以上用意し、画面に出た件数とposts_per_pageの値を目で見比べます。その後、0件・1件になる条件と、実際に使う件数も試します。次に、本番に近い構成の検証サイトであるステージングで、PHP、データ、キャッシュ、ページ送り、PC・スマホの差を確認します。本番のデータベースを共有せず、通知メールや決済も実送信・実課金につながらない状態にします。

WordPressのWP_DEBUGやWP_DEBUG_LOGは、ローカル・ステージングで原因を調べるために使います。公式資料は、これらのデバッグ機能を公開中の本番サイトで使うことを推奨していません。画面へエラーを出さずログで確認し、検証後は設定を戻します。

XServer for WordPressのステージング同期では、wp-content内のファイルとデータベースが同期対象で、WordPress本体とPHPバージョンは同期されません。これは同サービス固有の同期仕様です。利用する場合は、本番とステージングのバージョンを先に揃え、同期方向と対象を確認してください。古い検証用データベースを本番へ同期すると、本番で増えたデータを上書きするおそれがあります。コードだけの変更でデータベース同期が必要かも、分けて判断します。

新着3件の表示と、0件のときを見比べる

先ほどのパーツを動かすと、次のように新着記事のタイトルが3件並びます。サンプルサイトには先頭固定の記事もありますが、優先表示を無効にしているため、通常の記事と同じように公開日の新しい順で並んでいます。

確認はWordPress 7.1、PHP 8.4.20のローカル環境で行いました。試すために取得候補を1件・0件へ絞ると、1件だけのリンク、または「表示できる記事はありません。」という案内へ切り替わります。こうした少ない件数でも空白や警告にならないか、確認しておきましょう。試験用の候補制限は、上の完成コードには含めていません。

一覧の後でwp_reset_postdata()を呼ぶと、元の固定ページID83へ戻ることも確認できました。確認した内容をまとめると、次のとおりです。

ここで確認するのは、WP Query Builderが任意のサイトデータまで保証することではありません。同じ$argsでも、投稿タイプ、保存値、件数、他のプラグインやフックが違えば結果は変わります。自分の検証環境で同じ観点を再確認してください。

反映後に壊れたら、変更を増やさず元へ戻す

画面が真っ白になったり「サイトに重大なエラーがありました」と表示されたりしたら、別の修正を次々に足しません。最初に、直前に変更したファイルをバックアップへ戻します。

構文エラーと、結果が0件になる問題は分けます。構文エラーならまずファイルを戻し、0件でもサイトが動いているならpost_type、post_status、スラッグ、ID、メタキーを最小条件から確認します。

コードを貼る前に確認する公式資料

子テーマやサイト固有プラグインへ置く理由、バックアップとデバッグの方法、追加ループ後に投稿データを戻す処理は、次の公式資料で確認できます。

生成コードを貼る前のよくある質問

ここまでの内容で迷いやすい点を、質問と回答に分けて整理します。