WordPress Logo WordPress のテンプレートタグ

更新日:2019年03月12日

作成日:2019年01月18日

テンプレートタグ

テンプレートタグとは、WordPress に対して何かを表示させたい時やあるデータを取得させたい場合などに使う「PHP で記述された WordPress が定義した関数」です。

以下は WordPress 公式テーマ「Twenty_Nineteen」のテンプレートパーツ(header.php)のヘッダー部分の記述です。<?php と ?> に囲まれた language_attributes() や bloginfo()、wp_head() などがテンプレートタグになります。

Twenty_Nineteen
<!doctype html>
<html <?php language_attributes(); ?>>
<head>
  <meta charset="<?php bloginfo( 'charset' ); ?>" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="profile" href="https://gmpg.org/xfn/11" />
  <?php wp_head(); ?>
</head>

<body <?php body_class(); ?>>
<div id="page" class="site">
・・・以下省略・・・

以下は、bloginfo() というテンプレートタグです。HTML ファイルの中に PHP を記述する場合は、以下のように <?php と ?> の間に記述します。また、テンプレートタグには、パラメータ(引数)が用意されているものがあります。

<meta charset="<?php bloginfo( 'charset' ); ?>">

指定するパラメータの値により、表示する内容や実行する内容が異なります。bloginfo( 'charset' ) では「文字コード(UTF-8)」を、bloginfo( 'name' ) では「サイトのタイトル」を表示します。

個々のテンプレートタグに関しては以下のページを参照ください。

テンプレートタグが定義されている場所

テンプレートタグの定義は、WordPress をインストールしたディレクトリ内の wp-includes フォルダ内に ***-template.php というファイルに記述されています(*** はテンプレートタグの分類)。

wp-includes フォルダ内のテンプレートタグを定義してあるファイルの例

テンプレートタグの調べ方

以下はテンプレートタグを調べるのに便利なサイトです。それぞれのサイトには右上に検索ボックスがあるので、調べたい関数(テンプレートタグ)やフィルタ名などを入力して検索することができます。

ソース(定義)の確認方法

個々のテンプレートタグのソース(定義)は wp-includes フォルダ内を検索して調べることもできますが、以下のような方法で調べることもできます。

WordPress Developer Resources」ではそれぞれのテンプレートタグのソースや定義してあるファイルなどを確認することができます。トップページでは、検索する文字列を入力すると候補が表示されるので便利です。

WordPress Developer Resources サイトのトップページのスクリーンショット

確認したいテンプレートタグのページに行くと「Source #」というセクションがあるのでそこの「File:」の右にはそのテンプレートファイルが定義されているファイル名が表示されています。

「Expand full source code」をクリックするとソース全体が表示されます。また、「View on Trac」をクリックするとソースを定義してあるファイルの中のソース部分を表示してくれます。

WordPress Developer Resources サイトのテンプレートタグページのスクリーンショット

上記最後の「PHP Cross Reference of WordPress」も関数のソース(定義)などを調べるのに便利なサイトです。

少しわかりにくいですが、サイトにアクセスすると、右上に「Search」と言う白い文字のリンクがあるのでマウスオーバーするかクリックすると検索ボックスが表示されます。

PHP Cross Reference of WordPress サイトのスクリーンショット

検索する関数(テンプレートタグ)などを入力して Enter キーを押すと、その関数が定義されているファイル名及び行番号や、それを参照しているファイルなどのリンクが表示されます。

PHP Cross Reference of WordPress サイトでの検索結果のスクリーンショット

非推奨のタグ

テンプレートタグの中には、「非推奨」となっているタグがあります。

「非推奨(Deprecated)」というのは「以前は使用されていたが、現在はより良いテンプレートタグがあるのでそちらを使用してください」と言うような意味ですが、将来的には非推奨のタグは廃止になる可能性もあるので、なるべく非推奨のタグは使わないようにします。

非推奨の例として、良く使われる bloginfo() では以下のパラメータの使用は非推奨となっています。(この場合、タグ自体ではなく使用するパラメータが非推奨)

bloginfo()に代わるテンプレートタグ
非推奨パラメータ
bloginfo()
get_bloginfo()
推奨されているタグ 意味
'wpurl' echo site_url() 「一般設定」の "WordPress アドレス (URL)"
'siteurl'
'home'
'url'
echo home_url() 「一般設定」の "サイトアドレス (URL)"
WordPress をインストールしたディレクトリとは別のディレクトリにサイトのホームページを設定した場合のアドレス
'stylesheet_url' echo get_stylesheet_uri() 有効な(アクティブな)テーマのスタイルシートファイルの URL(通常は style.css)
'stylesheet_directory' echo get_stylesheet_directory_uri() 有効な(アクティブな)テーマのスタイルシートファイルのディレクトリの URL
'template_url'
'template_directory'
echo get_template_directory_uri()
子テーマのディレクトリは echo get_stylesheet_directory_uri()を使用
有効な(アクティブな)テーマのディレクトリの URL。
子テーマの場合、get_bloginfo('template_url')は親テーマのディレクトリのURLを返す。

廃止された関数は「wp-includes/deprecated.php (5.0.3)」に記載されています( * Deprecated functions from past WordPress versions. 以下)。但し、これを毎回確認するのは大変なので、作成したテーマに非推奨のテンプレートタグが使われていないかを調べるには、Theme Check プラグインを使用するのが便利です。Theme Check プラグインは、テーマで使用されている非推奨のテンプレートタグなどをチェックしてくれます。

個々のテンプレートタグの詳しい説明は以下の公式リファレンスに記載されています。

  • WordPress Codex(日本語): bloginfo
    非推奨のパラメータには「xxxx を用いることを推奨します」と記載されています。

  • WordPress Code Reference(英語): bloginfo
    非推奨のパラメータには「Deprecated since version 2.2.」や「Consider echoing xxxx instead.」と記載されています。

テンプレートタグの引数

テンプレートタグの引数(パラメータ)の指定方法には、引数を順番に並べる方法と、1つの引数で複数のパラメータ(パラメータを格納した配列)を指定する方法があります。

WordPress Codex(日本語):テンプレートタグ/タグパラメータの渡し方

引数を順番に並べて指定する例

ページのタイトルを出力する the_title() は引数を順番に並べて指定するテンプレートタグです。以下が書式とパラメータ(引数)です。

<?php the_title( $before, $after, $echo ); ?>  
パラメータ 種類(型) 説明 初期値
$before 文字列 タイトルの前に置くテキスト(オプション) なし
$after 文字列 タイトルの後に置くテキスト(オプション) なし
$echo 真偽値 タイトルを表示する場合は true、表示せず返す(値として取得する)場合は false(オプション) true

the_title() は、以下のように引数をカンマ区切りで順番に並べて値を指定します。

the_title('<h1>', '</h1>', true);

上記の場合、3番目の引数はデフォルトと同じ値なので、以下のように省略しても同じことになります。

the_title('<h1>', '</h1>');

引数を全て省略した場合は、デフォルト値が使われます。

the_title();
//以下を指定したのと同じ
the_title('', '', true);

但し、例えば1番目と2番目はデフォルトの引数を使い、3番目はデフォルト以外を指定する場合、1番目と2番目の引数は省略できず、以下のように記述しなければなりません。

the_title('', '', false);

1つの引数で複数のパラメータを指定する方法

WordPress の引数の多いテンプレートタグや関数では、1つの引数に複数のパラメータを指定するようになっています。

例えば、各種アーカイブリストを出力するテンプレートタグ wp_get_archives() の書式と引数は以下のようになっています。

<?php wp_get_archives( $args ); ?>
wp_get_archives() の引数 (キーと値)
キー デフォルト値 概要
type 文字列 monthly 出力するアーカイブのタイプを、文字列で指定。
yearly:年別
monthly :月別(初期値)
daily:日別
weekly:週別
postbypost :最近の投稿
alpha:投稿のタイトルの文字コード順
limit 数値 なし リストに出力する件数を指定
format 文字列 html リストの形式を文字列で指定。
html (初期値) 各アーカイブへのリンクを li 要素で囲む。リストを囲む ul 要素は出力されないので、<ul>と</ul>で囲む必要がある。
option - 各アーカイブへのリンクを option 要素で囲む(ドロップダウン用)
link - 各アーカイブのアドレスを link 要素として出力。
custom - 各アーカイブへのリンクの a 要素のみを出力。
before 文字列 なし リストの各項目の前に出力する文字列を指定
after 文字列 なし リストの各項目の後に出力する文字列を指定
show_post_count 0または1 0 0:投稿数を表示しない
1:アーカイブごとの投稿数を表示する
echo 0または1 1 1なら結果を出力。0 なら結果を戻り値として返す

クエリ文字列型引数

以下のように指定すると、アーカイブリストを年別(type)で10件(limit)表示します。指定したパラメータ以外はデフォルト値が使われます。

wp_get_archives('type=yearly&limit=10')

クエリ文字列型タグは、引数全体をシングルまたはダブルクォートで囲みます。そして、各引数を「キー = 値」という形式で入力し、それぞれをアンド記号(&)でつないでいきます。

クエリ文字列型タグは、すべての引数を指定することなく、必要な引数だけを変更(指定)することができます。また、クエリ文字列型の引数は、特定の順序で記述する必要はありません。

※クエリ文字列型のタグを使うときには、アンパサンドやシングル・ダブルクォーテーションなど使えない文字があります。こういった文字を使うときには、配列型引数を使う必要があります。

配列型引数

以下は、PHP の連想配列を利用した配列型引数を使った指定の例です。以下のように改行して記述できるため、パラメータが多い場合は見やすくなります。

wp_get_archives(array(
  'type'=>'yearly',
  'limit'=>10,)); 

配列型引数も、すべての引数を指定することなく、必要な引数だけを変更(指定)することができます。また、クエリ文字列型の引数は、特定の順序で記述する必要はありません。

また、配列型引数の場合、以下のように引数を任意の変数としてテンプレートタグと別に記述しておくこともできます。

$myArgs = array(
  'type' => 'yearly',
  'limit' => 10);
wp_get_archives($myArgs); 

引数の順番指定と複数のパラメータ指定が混在するテンプレートタグ

register_post_type() などは、順番指定と複数のパラメータを指定するタイプのテンプレートタグです。以下が書式です。

<?php register_post_type( $post_type, $args ); ?>
  • $post_type(文字列) 投稿タイプ (必須)
  • $args(配列)引数の配列。※詳細は省略

以下が指定例です。

register_post_type(
  'topics', //$post_type
  array(
    'label' => 'トピックス', 
    'labels' => array( 
      'add_new_item' => '新規トピックスを追加',
      'add_new' => '新規追加',
      'edit_item' => 'トピックスの編集',
      'view_item' => 'トピックスを表示',
      'search_items' => 'トピックスを検索',
      'not_found' => 'トピックスは見つかりませんでした。',
      'not_found_in_trash' => 'ゴミ箱にトピックスはありませんでした。',
    ),
    'public' => true,
    'hierarchicla' => false, 
    'has_archive' => true,
    'supports' => array( 
      'title',
      'editor',
      'thumbnail',
      'excerpt' 
    ),
    'menu_position' => 5  
  )
);

独自(代替)テンプレートタグ

functions.php に PHP の関数を定義することで、テンプレートタグと同様にその関数をテーマから呼び出すことができます。

例えば、月別アーカイブページの月・年名を表示するテンプレートタグ single_month_title() は、日本語環境で出力すると「5月2018」のようになってしまいます。

テンプレートタグ single_month_title() は、wp-include/general-template.php に以下のように定義されています。

function single_month_title($prefix = '', $display = true ) {
  global $wp_locale;

  $m = get_query_var('m');
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');

  if ( !empty($monthnum) && !empty($year) ) {
    $my_year = $year;
    $my_month = $wp_locale->get_month($monthnum);
  } elseif ( !empty($m) ) {
    $my_year = substr($m, 0, 4);
    $my_month = $wp_locale->get_month(substr($m, 4, 2));
  }

  if ( empty($my_month) )
    return false;

  $result = $prefix . $my_month . $prefix . $my_year;

  if ( !$display )
    return $result;
  echo $result;
}    

get_query_var() を使って年月の値を取得して、月の値を $wp_locale から言語設定に応じた値に変更して変数 $result に代入して出力または値を返すようになっています。

以下は上記関数の一部を変更して「2018年5月」のように出力または値を返す関数 single_month_title_jp() を functions.php に記述して定義する例です。

function single_month_title_jp($prefix = '', $display = true ) {
  global $wp_locale;

  $m = get_query_var('m');
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');

  if ( !empty($monthnum) && !empty($year) ) {
    $my_year = $year;
    $my_month = $wp_locale->get_month($monthnum);
  } elseif ( !empty($m) ) {
    $my_year = substr($m, 0, 4);
    $my_month = $wp_locale->get_month(substr($m, 4, 2));
  }

  if ( empty($my_month) )
    return false;

  //$result = $prefix . $my_month . $prefix . $my_year; ※この行を以下に書き換えただけ
  $result = $my_year .'年' .$prefix .$my_month ;

  if ( !$display )
    return $result;
  echo $result;
}    

以下のように定義してもほぼ同じ結果になります。

function single_month_title_jp($prefix = '', $display = true ) {
  $year = get_query_var('year');
  $monthnum = get_query_var('monthnum');
  $result = $year .'年' .$prefix .$monthnum .'月';

  if ( !$display )
    return $result;
  echo $result;
}

コロン(:)を使った構文

テンプレートの記述を見ると、<?php if (have_posts()) : ?> ~ <?php endif; ?> のようにコロン(:)を使って波括弧 { } を使わない記述がありますが、これは PHP の制御構造の別の構文で、Web ページに記述する(HTML に埋め込む)際に使用すると便利です。

この構文は、if, switch, while, for, foreach の制御構造で使用することができます。

参考:PHP マニュアル「制御構造に関する別の構文

例えば、通常の if 文の場合、以下のような記述になります。

<?php
$x = 3;
if($x >= 5) {
  echo '$x は5以上です。';
}else{
  echo '$x は5未満です。';
} 
?>

上記をコロン(:)を使った構文に書き換えると以下のようになります。最後の閉じ括弧の代わりに endif; を記述しています。

<?php
$x = 3;
if($x >= 5) :
  echo '$x は5以上です。';
else:
  echo '$x は5未満です。';
endif; 
?>

以下は、Web ページに記述する(HTML に埋め込む)場合の例です。波括弧を使って記述するよりスッキリと記述できます。

<?php if ($username == 'Suzuki'): ?>
<p>Suzuki さん、こんにちは</p>
<?php elseif ($username == 'Tanaka'): ?>
<p>Tanaka さん、こんにちは</p>
<?php else: ?>
<p>名無しさん、こんにちは</p>
<?php endif; ?>

echo とテンプレートタグ

テンプレートタグには、bloginfo() のように値をブラウザに出力(表示)するものと、get_the_title() のように値を返すだけのものがあります。

the_ で始まるテンプレートタグ
the_ID や the_title といった「the_」を前置するテンプレートタグは、echo を行っているテンプレートタグでブラウザに出力されます。
get_ で始まるテンプレートタグ
get_the_ID や get_the_title など「get_」を前置するテンプレートタグは、echo を行わず値を返すテンプレートタグです。ブラウザに出力するには echo が必要です。出力する際には、必要に応じてエスケープ処理をします。

また、引数の指定により echo を行うか、値を返すかの選択のできるテンプレートタグもあります。例えば、the_title の display 引数に false を指定すると echo はされず値としてタイトルが返ってきます。但し、全てのタグがこのような規則になっているわけではないので、タグごとに確認する必要があります。

データを返すだけの関数と対になるデータを出力する関数の例
出力前のデータを得る関数 対になる出力をする関数
get_the_title the_title
get_the_content the_content
get_the_ID the_ID
get_the_permalink the_permalink
get_the_excerpt the_excerpt
get_the_category the_category
get_the_tags the_tags
adjacent_post_link next_post_link/previous_post_link
get_next_posts_link next_posts_link
get_previous_posts_link previous_posts_link
get_body_class body_class
get_post_class post_class
the_xxxx と get_xxxx

the_permalink() は投稿のパーマリンク(URL)を表示する関数ですが、これに対して get_permalink() は投稿のパーマリンク(URL)を取得して返す関数です。

このため、以下のように echo を使って get_permalink() で取得した値を出力すれば、the_permalink() と同じことができるように思えますが、異なる点があるので注意が必要です。

<a href="<?php echo get_permalink();?>">link</a>

the_permalink() の定義を見てみると以下のようになっていて、get_permalink() で取得した値に the_permalink と言うフィルタを適用し、その後 esc_url() でエスケープ処理をしています。

function the_permalink( $post = 0 ) {
    /**
    * Filters the display of the permalink for the current post.
    *
    * @since 1.5.0
    * @since 4.4.0 Added the `$post` parameter.
    *
    * @param string      $permalink The permalink for the current post.
    * @param int|WP_Post $post      Post ID, WP_Post object, or 0. Default 0.
    */
  echo esc_url( apply_filters( 'the_permalink', get_permalink( $post ), $post ) );
}

つまり、単に get_permalink() で取得した値を echo で出力する場合と the_permalink() で出力する場合とでは以下のような違いがあります。

  • フィルタが適用されない(プラグイン等がこのフィルタを利用している場合、その処理が行われない)
  • エスケープ処理がされない(セキュリティ上の問題)

もし、the_permalink() で出力される値と全く同じ値を取得するには以下のようになります。

$permalink_value = esc_url( apply_filters( 'the_permalink', get_permalink() ) );

このため、the_xxxx と get_xxxx と言う関数がある場合、出力する際は the_xxxx と言う方の関数を使うようにします。

get_xxxx と言う関数を使って値をカスタマイズして出力する場合は、必要に応じてエスケープ処理をするようにします。また、場合によってはフィルタの適用など他の処理も必要になるかも知れません。それぞれの関数のソースなどを確認して(または、検索などして)判断する必要があります。(テンプレートタグの調べ方