初心者向けWordPressのPHP｜テンプレート編

WordPressのテーマを自作しようとすると、ファイルや関数の多さに戸惑いがちです。この記事では、「お知らせ」の一覧ページを例に、ページを表示するファイルに書くPHPを読み解いていきます。PHPのファイルで作る「クラシックテーマ」が前提です。

テンプレートに書くPHPの全体像

WordPressのページは、ページごとの中身を書くファイルが、上下の共通部分を読み込んで作られます。この記事では、この3種類のファイルに書くPHPを扱います。

中身を書くテンプレートファイルは、役割ごとのかたまり（ブロック）が上から並んでいます。この記事では、会社サイトの「お知らせ」の一覧ページを例に、次の5つのブロックを扱います。

5つをつなげたコードの全文は、記事の最後の「完成形のコード」にまとめています。

この後は、コードを読むための前提、5つのブロックの解説、表示を工夫するための機能の順に並んでいます。前提の内容はどのブロックにも関わるため、初めての人は上から読み進めてください。知りたい内容が決まっている場合は、サイドバー（スマホは右下のボタン）の「目的から探す」から移動できます。

テーマに機能を追加するPHPは、「functions.phpの書き方」で紹介しています。

読む前に知っておくこと

ブロックを読む前に、PHPの書き方と、テーマのファイルに共通する決まりを押さえます。

PHPの書き方

テンプレートファイルでは、HTMLの中にPHPを埋め込んで書きます。

<?php if ( 条件 ) : ?>       <!-- 条件に合うときだけ -->
  <p>ここが表示される</p>
<?php endif; ?>              <!-- ifの終わり -->

どのファイルが使われるかを知る

テンプレート階層は、表示するページの種類に応じて、使うテンプレートファイルをWordPressが自動で選ぶ仕組みです。

ファイルは、スラッグ※1などを名前に含む専用のものから順に探されます。例えば固定ページでは、次の順番です。

この記事で例にする「お知らせ」の一覧ページでは、archive-news.php というファイルが使われます。news は、お知らせの投稿タイプの名前です。

※1：スラッグ…ページのURLに使われる、ページごとの名前。

書き忘れると困るコードを入れる

header.php と footer.php には、WordPressやプラグインが出力を差し込むための関数を書きます。

header.php

<head>
  <?php wp_head(); ?>           <!-- ① -->
</head>
<body <?php body_class(); ?>>  <!-- ② -->
<?php wp_body_open(); ?>       <!-- ③ -->

footer.php

  <?php wp_footer(); ?>  <!-- bodyの閉じタグの前に書く -->
</body>

wp_head() と wp_footer() がないと、CSS・JSやプラグインの出力がページに差し込まれません。wp_body_open() は、WordPress 5.2で追加された関数です。

不正な入力からサイトを守る

エスケープは、出力するデータから不正なHTMLやscriptタグなどを取り除き、安全に表示する処理です。公式の推奨は「出力する直前にエスケープする」ことです。

<p><?php echo esc_html( $text ); ?></p>             <!-- テキスト -->
<img alt="<?php echo esc_attr( $alt ); ?>">         <!-- 属性値 -->
<a href="<?php echo esc_url( $link ); ?>">link</a>  <!-- URL -->

5つのブロックを順に読む

ここからは、「お知らせ」の一覧ページ（archive-news.php）を、全体像の図の①〜⑤の順に読んでいきます。

共通パーツを読み込む

ヘッダーやフッターは、どのページでも同じ内容です。ページごとに書くと修正が大変なので、別のファイルに分けて、各テンプレートファイルから読み込みます。

<?php get_header(); ?>  <!-- 上の共通部分を読み込む -->
<main>
</main>
<?php get_footer(); ?>  <!-- 下の共通部分を読み込む -->

このブロックを書くと、header.php と footer.php の中身が、書いた位置に差し込まれます。ページの中身は、間の main の中に書いていきます。

get_template_part() は、読み込むパーツに値を渡すこともできます（WordPress 5.5以降）。

記事一覧を表示する

一覧ページには、複数のお知らせが並びます。ループは、表示する投稿を1件ずつ取り出して、同じHTMLを繰り返し出力する仕組みです。

<?php if ( have_posts() ) : ?>         <!-- ① -->
  <?php while ( have_posts() ) : ?>    <!-- ② -->
    <?php the_post(); ?>               <!-- ③ -->
    <h2><?php the_title(); ?></h2>
  <?php endwhile; ?>
<?php endif; ?>

このブロックを書くと、お知らせの件数ぶん、間に書いたHTMLが繰り返し出力されます。上の例では、タイトルの見出しがお知らせの数だけ並びます。

ページ本来の投稿を表示するのがメインループ、WP_Query というクラス※2で別の投稿を並べるのがサブループです。サブループの後は、wp_reset_postdata() で元に戻します。

古い解説で見かける query_posts() は、公式が「避けるべき」としている書き方です。

※2：クラス…関連するデータと処理をひとまとめにした設計図のようなもの。new を付けて使います。

タイトルや本文を表示する

ループで取り出したお知らせの、タイトルや日付を表示します。テンプレートタグは、データベースから記事の情報を取り出して表示する関数です。

<time><?php the_time( 'Y.m.d' ); ?></time>  <!-- ① -->
<h2>
  <a href="<?php the_permalink(); ?>">    <!-- ② -->
    <?php the_title(); ?>                 <!-- ③ -->
  </a>
</h2>
<?php the_excerpt(); ?>                   <!-- ④ -->

このブロックを書くと、お知らせ1件ごとに、日付・リンク付きのタイトル・抜粋が表示されます。テンプレートタグの多くは、ループの中に書かないと正しく表示されません。

アイキャッチ画像を表示する

お知らせごとの画像を表示します。アイキャッチ画像は設定されていない投稿もあるため、あるかどうかを確かめてから表示します。

<?php if ( has_post_thumbnail() ) : ?>      <!-- 設定されているか確認 -->
  <?php the_post_thumbnail( 'medium' ); ?>  <!-- サイズを指定して表示 -->
<?php endif; ?>

このブロックを書くと、アイキャッチ画像が設定されたお知らせにだけ、画像が表示されます。

アイキャッチ画像を使うには、先に functions.php で機能を有効にしておく必要があります。有効にしないと、投稿の編集画面に設定欄が表示されません。

※3：値を返す…画面には出力せず、取得した結果を変数などに受け取れる形で渡すこと。

ページ送りを付ける

お知らせが増えると、1ページに収まらなくなります。ページネーションは、一覧を複数のページに分けて、前後へ移動できるようにする仕組みです。

<?php endwhile; ?>
<?php the_posts_pagination(); ?>  <!-- ループの後に書く -->

このブロックを書くと、一覧の下に番号付きのページ送りが表示されます。1ページの件数は、管理画面の「設定」→「表示設定」で決まり、初期値は10件です。お知らせだけ件数を変える方法は、「functions.phpの書き方」で紹介しています。

さらに表示を工夫する

5つのブロックに慣れたら、サイトに合わせて次のような表示を足していきます。ここでは紹介にとどめます。

入力欄の値を表示する

カスタムフィールドは、投稿に独自の入力項目を追加して、その値を表示する仕組みです。

get_field() はWordPress本体ではなく、ACFプラグインの関数です。どちらの関数で取得した値も、出力する前にエスケープが必要です。

ページごとに表示を変える

条件分岐タグは、表示中のページを判定して true／false※4 を返す関数で、if と組み合わせて使います。

条件分岐タグは、functions.php に直接書いても動きません。functions.php は、表示するページが決まる前に読み込まれるためです。テンプレートファイルの中か、フックの中で使います。

※4：true／false…判定の結果を表す値。条件に当てはまれば true、当てはまらなければ false になります。

メニューを表示する

管理画面の「外観」→「メニュー」で作ったメニューを、header.php などに表示します。

メニューを表示するには、先に functions.php でメニューの位置を登録しておく必要があります。

ウィジェットを表示する

ウィジェット※5を置けるエリアを、sidebar.php などに表示します。

ウィジェットエリアも、先に functions.php で登録しておく必要があります。

※5：ウィジェット…新着記事や検索フォームなど、管理画面から追加できる部品。

検索結果ページを作る

サイト内検索のフォームと、検索結果のページを用意します。

search.php がない場合は、index.php が使われます。検索結果だけ見た目を変えたいときは、search.php を作ります。

完成形のコード

5つのブロックをつなげると、次の archive-news.php になります。

<?php get_header(); ?>                   <!-- ① -->
<main>
  <?php if ( have_posts() ) : ?>         <!-- ② -->
    <?php while ( have_posts() ) : ?>
      <?php the_post(); ?>
      <article>
        <time>                           <!-- ③ -->
          <?php the_time( 'Y.m.d' ); ?>
        </time>
        <h2>
          <a href="<?php the_permalink(); ?>">
            <?php the_title(); ?>
          </a>
        </h2>
        <?php the_excerpt(); ?>
        <?php if ( has_post_thumbnail() ) : ?> <!-- ④ -->
          <?php the_post_thumbnail( 'medium' ); ?>
        <?php endif; ?>
      </article>
    <?php endwhile; ?>
    <?php the_posts_pagination(); ?>     <!-- ⑤ -->
  <?php endif; ?>
</main>
<?php get_footer(); ?>                   <!-- ① -->

「お知らせ」という投稿の種類そのものは、functions.php で登録します。登録の方法は、「functions.phpの書き方」で紹介しています。

さいごに

まとめ

テンプレートファイルは、役割ごとのブロックが並んだファイルです。共通パーツを読み込み、ループで投稿を取り出し、その中でタイトルや画像を表示する、という形はどのページでも同じです。

ほかのテーマのテンプレートファイルを見るときも、「このブロックは何をしているか」を探しながら読んでみてください。

よくある質問

自作テーマでCSSやプラグインの機能が反映されません

header.php に wp_head()、footer.php に wp_footer() が書かれているか確認しましょう。この2つがないと、CSS・JSやプラグインの出力がページに差し込まれません。

書く位置は「書き忘れると困るコードを入れる」で解説しています。

新着記事を並べた後、ページの表示がおかしくなりました

WP_Query で別の投稿を並べた後は、wp_reset_postdata() で投稿データを元に戻す必要があります。戻し忘れると、その後の表示に別の投稿のデータが使われます。

ループの書き方は「記事一覧を表示する」で解説しています。

get_field() はWordPressの標準の関数ですか？

いいえ。get_field() はACF（Advanced Custom Fields）プラグインの関数です。プラグインを使わない場合は、WordPress標準の get_post_meta() を使います。

使い分けは「入力欄の値を表示する」で解説しています。

エスケープはいつすればいいですか？

公式の推奨は、出力する直前です。出力する場所に合わせて、テキストには esc_html()、属性値には esc_attr()、URLには esc_url() を使います。

使い分けは「不正な入力からサイトを守る」で解説しています。

functions.php に条件分岐タグを書いたのに動きません

functions.php は、表示するページが決まる前に読み込まれます。そのため、条件分岐タグを直接書いても判定できません。テンプレートファイルの中か、フックの中で使いましょう。

条件分岐タグの種類は「ページごとに表示を変える」で解説しています。

参考にした公式情報

WordPress公式 開発者向けドキュメント

テンプレート階層やループ、エスケープなど、テーマ制作の基本を確認できます。

公式ページを開く

ACF公式 ドキュメント

get_field() がACFプラグインの関数で、出力前にエスケープが必要なことを確認できます。

公式ページを開く

PHP公式 マニュアル

PHPの開始タグと終了タグの役割を確認できます。

公式ページを開く