WordPress Logo WordPress ループで使うテンプレートタグや関数

WordPress のループでは WordPress がデータベースから取得した記事のデータから、テンプレートタグや関数を使ってその記事に関する情報を出力したり取得することができます。

以下はループで良く使うテンプレートタグの使い方などに関しての覚え書きです(ループの外で使うテンプレートタグやフックなどについても掲載しています)。

更新日:2019年05月18日

作成日:2019年04月16日

タイトル

タイトルを出力したり取得するテンプレートタグ。

the_title

現在の投稿や固定ページのタイトルを表示、または取得して返します。

the_title( $before, $after, $echo )

パラメータ
  • $before(文字列):(オプション)タイトルの前に置くテキスト(HTML)。初期値:''(空文字列)
  • $after(文字列):(オプション)タイトルの後ろに置くテキスト(HTML)。初期値:''(空文字列)
  • $echo(真偽値):(オプション)タイトルを表示する場合は true(初期値)、タイトルを出力せずに値として返す場合は false。
戻り値
$echo に false を指定した場合は、タイトルの値(処理された結果)。
利用可能箇所
ループ内

タイトルを出力するには、テンプレートに以下を記述します。現在の個別ページのタイトルに入力されている文字列が出力されます。

<?php the_title(); ?>

タイトルに HTML タグが含まれていれば HTML タグもそのまま出力されます(エスケープされません)。

投稿入力外面(タイトル部分)

タイトルの前後を <h3 class="foo"> と </h3> のタグで囲んで h3 要素として出力場合は以下のように記述することができます。

このように記述すると、もしタイトルが空の場合には不要な HTML 要素(h3 タグ)は出力されません。

<?php the_title('<h3 class="foo">', '</h3>'); ?>

<!-- 以下のように出力される  -->
<h3 class="foo">タイトルの文字</h3>

以下のように記述してもほぼ同じです。この場合、もしタイトルの文字列が空の場合は(あまりそういうことはないと思いますが) h3 のタグは HTML 上に残ります。

<h3 class="foo"><?php the_title(); ?></h3>

以下がこの関数のソースです。

4~6行目でタイトルの文字が空の場合は、何もせずに終了しています。

8行目で get_the_title() で取得した値にパラメータで指定した文字列を連結しています。

10~14行目でパラメータ $echo の値により出力するか値を返しています。

function the_title( $before = '', $after = '', $echo = true ) {
  $title = get_the_title();

  if ( strlen( $title ) == 0 ) {
    return;
  }

  $title = $before . $title . $after;

  if ( $echo ) {
    echo $title;
  } else {
    return $title;
  }
}

パラメータ $echo

第3パラメータ $echo に false を指定した場合、タイトルを出力せずに値として返します。

以下の場合、変数 $my_title にはタイトルの文字列が格納され、第1及び第2パラメータに何も指定していないので、get_the_title() で取得する値と同じになります。

<?php $my_title = the_title('', '', false); ?>

第1及び第2パラメータを指定すると、それらを使って組み立てた文字列が格納されます。

<?php $my_title = the_title('<h3 class="foo">', '</h3>', false); ?>

<!-- 以下の文字列(HTML を含む)が $my_title に格納される  -->
<h3 class="foo">タイトルの文字</h3>

タイトルにそのページのリンクを付けて出力

get_permalink() を使ってそのページのリンクを付けるには以下のように記述することができます。

<?php the_title( '<h2><a href="' . esc_url( get_permalink() ) . '">', '</a></h2>' ); ?>

PHP 関数 sprintf() を使うと以下のように記述できます。

<?php the_title( sprintf( '<h2><a href="%s">', esc_url( get_permalink() ) ), '</a></h2>' ); ?>

以下のように記述してもほぼ同じ結果になります(タイトルが空の場合を除く)。

<h2><a href="<?php echo esc_url( get_permalink() ); ?>"><?php the_title(); ?></a></h2>

title 属性や alt 属性にタイトルを出力する場合

投稿や固定ページのタイトルには HTML を含めることができます。また、タイトルの文字列に「"」や「'」がエスケープされずに記述されている可能性もあります。

そのため、HTML 要素の属性値としてタイトルを出力する場合やエスケープ処理した値を出力したい場合は、the_title_attribute() を使用します。

get_the_title

投稿のタイトルを取得して返します。ループの外で使う場合はパラメータに ID または投稿オブジェクトを指定します。

get_the_title( $post )

パラメータ
$post(int|WP_Post):(オプション)投稿の ID または投稿を特定するオブジェクト。デフォルトは、現在の投稿。
戻り値
投稿のタイトル。

以下は、ID が 72 の投稿のタイトルを変数 $my_title に代入する例です。

<?php $my_title = get_the_title(72); ?>

以下は get_the_title() のソースです。

値を返す前に the_title フィルターを適用します。

function get_the_title( $post = 0 ) {
  $post = get_post( $post );

  $title = isset( $post->post_title ) ? $post->post_title : '';
  $id    = isset( $post->ID ) ? $post->ID : 0;

  if ( ! is_admin() ) {
    if ( ! empty( $post->post_password ) ) {

      /**
       * Filters the text prepended to the post title for protected posts.
       * The filter is only applied on the front end.
       * @since 2.8.0
       * @param string  $prepend Text displayed before the post title.
       *                         Default 'Protected: %s'.
       * @param WP_Post $post    Current post object.
       */
      $protected_title_format = apply_filters( 'protected_title_format', __( 'Protected: %s' ), $post );
      $title = sprintf( $protected_title_format, $title );
    } elseif ( isset( $post->post_status ) && 'private' == $post->post_status ) {

      /**
       * Filters the text prepended to the post title of private posts.
       * The filter is only applied on the front end.
       * @since 2.8.0
       * @param string  $prepend Text displayed before the post title.
       *                         Default 'Private: %s'.
       * @param WP_Post $post    Current post object.
       */
      $private_title_format = apply_filters( 'private_title_format', __( 'Private: %s' ), $post );
      $title = sprintf( $private_title_format, $title );
    }
  }

  /**
   * Filters the post title.
   * @since 0.71
   * @param string $title The post title.
   * @param int    $id    The post ID.
   */
  return apply_filters( 'the_title', $title, $id );
}

the_title_attribute

ページのタイトルを表示、または取得して返します。

但し、タイトル部分に HTML タグを含んでいる場合は以下の関数を使った処理によりそれらを除去し HTML 属性として使えるようにクリーンな値にします。

  • strip_tags():文字列から HTML および PHP タグを削除する PHP 関数
  • esc_attr():HTML で特別な意味を持つ文字を変換する WordPress 関数

また、パラメータ(引数)はクエリ文字形式または配列型(連想配列)で指定する必要があります。(関連ページ:テンプレートタグの引数

the_title_attribute( $args )

パラメータ
  • $before(文字列):(オプション)タイトルの前に置くテキスト(HTML タグは除去されます)。
  • $after(文字列):(オプション)タイトルの後ろに置くテキスト(HTML タグは除去されます)。
  • $echo(真偽値):(オプション)タイトルを表示する場合は true(初期値)、タイトルを出力せずに値として返す場合は false。
  • $post(整数/オブジェクト):(オプション)タイトルを取得する投稿の ID または投稿オブジェクト。デフォルトは現在の投稿。

クエリ文字形式または配列型(連想配列)で指定します。以下は同じことです。

//クエリ文字形式
<?php the_title_attribute( 'before=直前テキスト&after=直後テキスト' ); ?>

//配列型(連想配列)
<?php the_title_attribute( array( 'before' => '直前テキスト', 'after' => '直後テキスト' ) ); ?>

但し、クエリ文字形式で $echo パラメータに false を指定する場合は echo=0 とする必要があります。

戻り値
$echo に false を指定した場合は、タイトルの値(処理された結果)。

以下は、the_title_attribute() を使ってリンク(a 要素)の title 属性に値を設定する例です。

<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute( array( 'before' => '「', 'after' => '」へのリンク' ) ); ?>"><?php the_title(); ?></a>

上記を改行して見やすくすると以下のようになります。

the_title() で出力するタイトル文字列に a 要素でリンクを設定しその title 属性に the_title_attribute() を使って値(「タイトル文字列」へのリンク)を設定しています。

<a href="<?php the_permalink(); ?>" 
  title="<?php the_title_attribute( array( 
    'before' => '「', 
    'after' => '」へのリンク' 
  ) ); ?>">
  <?php the_title(); ?>
</a>

PHP 関数 printf() を使って以下のように記述することもできます。

<?php printf('<a href="%s" title="%s">%s</a>', get_permalink(), the_title_attribute( array('before'=>'「', 'after'=>'」へのリンク', 'echo'=>false) ), get_the_title() ); ?>

以下が the_title_attribute() のソースです。

function the_title_attribute( $args = '' ) {
  $defaults = array(
    'before' => '',
    'after'  => '',
    'echo'   => true,
    'post'   => get_post(),
  );
  $r = wp_parse_args( $args, $defaults );

  $title = get_the_title( $r['post'] );

  if ( strlen( $title ) == 0 ) {
    return;
  }

  $title = $r['before'] . $title . $r['after'];
  $title = esc_attr( strip_tags( $title ) );  //タグの除去及びエスケープ処理

  if ( $r['echo'] ) {
    echo $title;
  } else {
    return $title;
  }
}

the_title フィルター

the_title フィルター(フック)を使えば出力されるタイトルをカスタマイズすることができます。

フィルターに処理を追加するには、add_filter() を使います。

the_title フィルターに登録するコールバック関数は引数に「タイトルの文字列」と「投稿 ID」を受け取ることができます。

function コールバック関数( $title, $id ) {
  //$title を加工して返す
  return $title;
}
add_filter( 'the_title',  コールバック関数名, 10, 2 );

投稿 ID を利用しない場合は引数に受け取る $id を省略できます。

function コールバック関数( $title ) {
  //$title を加工して返す
  return $title;
}
add_filter( 'the_title',  コールバック関数名, 10 );

the_title フィルターフックを使用する際の注意

the_title フィルターは影響範囲の大きいフィルターです。the_title() や the_title_attribute() などの関数の実行結果やナビゲーションメニューのタイトルなどにも影響があります。必要に応じて条件分岐などを使って適用範囲を限定します。

以下はタイトルの文字数が20文字以上の場合は、タイトルの文字数を20文字に丸めて最後に「...」を追加する方法です(以下の例は適用範囲を限定していないので全体に適用されます)。

PHP の関数 mb_strlen() で文字数を調べて 20文字より大きい場合は、mb_substr() で文字列の先頭から20文字を取り出して、文字列の最後に「...」を追加しています。第4パラメータのエンコーディングを省略すると内部文字エンコーディングが使用されます。

function trim_my_title( $title, $id ) {
  if ( mb_strlen( $title ) > 20 ) { 
    $title = mb_substr( $title, 0, 20, 'UTF-8' ). '...';
  }
  return $title;
}
add_filter('the_title', 'trim_my_title', 10, 2);

trim_my_title( $title, $id ) の $id は利用していないので、add_filter() のプライオリティ(デフォルトは10)と引数の数(デフォルトは1)の指定を省略して、以下のように記述しても同じです。

function trim_my_title( $title ) {
  if ( mb_strlen( $title ) > 20 ) { 
    $title = mb_substr( $title, 0, 20, 'UTF-8' ). '...';
  }
  return $title;
}
add_filter('the_title', 'trim_my_title');

以下はフィルタの適用範囲を「ループ処理内で且つ個別ページでない場合(トップページやアーカイブのループ内)」に限定する例です。

function trim_my_title( $title, $id ) {
  if ( in_the_loop() && !is_singular() ) {
    if ( mb_strlen( $title ) > 20 ) { 
      $title = mb_substr( $title, 0, 20, 'UTF-8' ). '...';
    }
  }
  return $title;
}
add_filter('the_title', 'trim_my_title', 10, 2);

以下はPHP 関数 mb_strimwidth() を使ってタイトルの文字数が20文字(半角英数字の場合は40文字)以上の場合に、タイトルの文字数を20文字に丸める方法です。前述の例より少し簡潔に記述できます。

function trim_my_title( $title, $id ) {
  if ( in_the_loop() && !is_singular() ) {
     $title = mb_strimwidth($title, 0, 40, "...", "UTF-8");
  }
  return $title;
}
add_filter('the_title', 'trim_my_title', 10, 2);

mb_strimwidth() は、指定した文字数で文字列を丸める関数で以下をパラメータに指定します。

  • $str:丸めたい文字列
  • $start: 開始位置のオフセット。文字列の始めからの文字数 (最初の文字は 0)
  • $width: 丸める幅(文字数)。マルチバイト文字(日本語)は1文字で2文字分。
  • $trimmarker:丸めた後にその文字列の最後に追加される文字列。
  • $encoding: 文字エンコーディング

上記の例の場合、$trimmarker に3文字(...)を指定しているのでタイトルに表示される文字数は実際はその分短くなります。

以下は「トップページやアーカイブなどのループ内の場合」に投稿記事が一定期間内に作成された場合にタイトルの最後に「New」と表示する例です。

以下の例では date() で取得した現在の日付のタイムスタンプと get_the_time() でその記事の書かれた日付のタイムスタンプの差分を 60*60*24*7 (7日間を秒数でカウントした値)と比較しています。

また、タイトルに追加する「New」は <span class="new_entry">New</span> としています。

function my_add_new_to_title( $title) {
  if ( in_the_loop() && !is_singular() ) {
    if ( date('U') - get_the_time('U') < 60*60*24*7 ){
      $title .= ' <span class="new_entry">New</span>';
    }
  }
  return $title;
}
add_filter('the_title', 'my_add_new_to_title');

以下は投稿が「foo」と言うカテゴリーに属している場合に、タイトルを空文字('')にする例です。

function suppress_title_if_foo( $title, $id = null ) {
  if ( in_category('foo', $id ) ) {
    return '';
  }
  return $title;
}
add_filter( 'the_title', 'suppress_title_if_foo', 10, 2 );

以下は投稿の ID が特定の ID の場合に、タイトルの文字列の前に「カスタマイズ:」と言う文字列を追加して出力する例です。

function change_my_post_title( $title, $id ) {
  global $post;
  if ( $post->ID == 72 ) {
    $title = 'カスタマイズ:' .$title;
  }
  return $title;
}
add_filter( 'the_title','change_my_post_title', 10, 2 );

登録されている関数

the_title フィルターに登録されている関数には以下のようなものがあります。

function priority 概要
wptexturize 10 引用符やアポストロフィ、ダッシュ、乗算記号などを変換
convert_chars 10 単独の & を &#038; に変換
capital_P_dangit 11 Wordpress を WordPress に変更(ソース

single_post_title

個別ページのループ外で記事のタイトルを出力または取得するのに使用します。

ループ内で投稿のタイトルは the_title() で出力することができますが、single_post_title() は個別ページ(single.php や page.php)のループの外(ループ開始前や終了後)でタイトルを出力する場合に利用できます。

パラメータに何も指定しなければ、投稿のタイトルを単純に出力します。

single_post_title( $prefix, $display )

パラメータ
  • $prefix(文字列):(オプション) 記事タイトルの前に出力するテキスト。
  • $display(真偽型):(オプション)タイトルを表示する場合は true(初期値)、タイトルを出力せずに値として返す場合は false。
戻り値
$display に false を指定した場合は、タイトルの文字列($prefix があればそれを付けた文字列)
利用可能箇所
個別ページのループの外

以下は、「タイトル:○○」のような形式でタイトルを出力する例です。

<h2><?php single_post_title( 'タイトル: ' ); ?></h2>

以下がソースです。

function single_post_title( $prefix = '', $display = true ) {
  $_post = get_queried_object();  //現在表示しているページのオブジェクトを取得

  if ( ! isset( $_post->post_title ) ) {
    return;  //post_title が設定されていなければ何もしない
  }

  /**
  * Filters the page title for a single post.
  * @since 0.71
  * @param string $_post_title The single post page title.
  * @param object $_post The current queried object as returned by get_queried_object().
  */
  $title = apply_filters( 'single_post_title', $_post->post_title, $_post );
  if ( $display ) {
    echo $prefix . $title;
  } else {
    return $prefix . $title;
  }
}

日付/時刻

投稿の日付や時刻を出力するテンプレートタグ

the_time

投稿や固定ページの公開時刻を表示します。

パラメータを指定しない場合は、管理画面「一般設定」の「時刻フォーマット」(「設定」→「一般」)で指定した書式で表示されます。

the_time( $d )

パラメータ
$d(文字列):(オプション)時刻を表示するフォーマット
戻り値
なし
利用可能箇所
ループ内

デフォルトでは、投稿を公開した時刻だけが管理画面「一般設定」の「時刻フォーマット」で指定した書式で出力されます。

<p>投稿時刻: <?php the_time(); ?></p>
<!-- (出力例)投稿時刻: 11:28 AM -->

パラメータとして書式設定の文字列(フォーマット)を渡すことで、その書式に沿った日時を出力することができます。

<p>投稿日時: <?php the_time('Y年n月j日(D)g時i分A'); ?></p>
<!-- (出力例)投稿日時: 2019年4月13日(土)11時28分AM -->

以下がフォーマットで使用できる主な記述子です。PHP の日付文字列の書式が使用できます。

フォーマットで利用できる主な記述子
記述子 概要
Y 年(4桁) 例:2019
y 年(2桁) 例:19
m 月 01 - 12
n 月 1 - 12
d 日 01 - 31
j 日 1 - 31
D 曜日(省略形) 月 - 日
l 曜日(長い形式) 月曜日 - 日曜日
h 時(12時間単位) 01 - 12
H 時(24時間単位) 01 - 24
g 時(12時間単位) 1 - 12
G 時(24時間単位) 1 - 24
i 分 00 - 59
s 秒 00 - 59
a 午前/午後 am | pm
A 午前/午後 AM | PM
U Unix Epoch (1970年1月1日0時0分0秒) からの秒数

get_the_time

現在の(または指定された)投稿や固定ページの時刻を指定したフォーマットで取得します。

get_the_time( $d, $post )

パラメータ
  • $d(文字列):(オプション)時刻を表示するフォーマット。省略時は、管理画面「一般設定」の「時刻フォーマット」(「設定」→「一般」)で指定した書式。
  • $post(整数 | オブジェクト):(オプション)投稿 ID または投稿オブジェクト。省略すると現在の投稿や固定ページ。
戻り値
指定された書式の時刻の文字列
利用可能箇所
パラメータの投稿 ID または投稿オブジェクトを指定しない場合はループ内、指定する場合はどこでも可能。

Unix タイムスタンプの取得

フォーマットに U を指定すると、その投稿を公開した日時(ローカル時刻)の Unix Epoch (1970年1月1日0時0分0秒) からの経過秒数を取得できます。

<?php $local_timestamp = get_the_time( 'U' ); ?>

PHP の date() 関数に U を指定すると現在の時刻のタイムスタンプを取得できるので、投稿の公開時刻との差分を調べれば経過した時間を取得できます。

以下は記事の公開日時からの経過日数を表示する例です。 86400 は 60(秒)x60(分)x24(時間)で、この値で割ることで経過秒数から日数を算出しています。 floor() は数値を切り捨てる PHP の関数です。

<p><?php echo floor((date('U') - get_the_date('U')) / 86400 ) ; ?> 日以上経過。</p>

取得した値の出力

以下は投稿の ID を指定して echo を使って出力する例です。$post->ID の代わりに直接 ID(整数)を指定することもできます。

また、時刻や日付を取得する関数の場合、get_xxxx と言う形式の関数でもエスケープ処理は必要はないと思われます。

<?php echo get_the_time( '', $post->ID ); ?>

the_date

現在の投稿や固定ページの公開(作成)日を表示します。

ループ内で複数の投稿を続けて出力する場合、最初の記事の日付のみが表示され、直前の投稿と日付(公開日)が同じであれば何も出力しません。そのため投稿を日付ごとにまとめて出力する場合に適しています。

同じ日付を繰り返し表示するには echo と get_the_date() または the_time() を使用します。

the_date( $dt, $before, $after, $echo );

パラメータ
  • $d(文字列):(オプション)日付を表示するフォーマット。省略時は、管理画面「一般設定」の「日付フォーマット」(「設定」→「一般」で指定した書式)。
  • $before(文字列):(オプション)投稿日の直前に出力するコードやテキスト
  • $after(文字列):(オプション)投稿日の直後に出力するコードやテキスト
  • $echo(真偽値):(オプション)投稿日を表示する場合は true(デフォルト)、表示しない(取得する)場合は false を指定
戻り値
出力する場合($echo が true)はなし、出力しない場合($echo が false)は結果の文字列
利用可能箇所
ループ内

日付を p 要素でマークアップする場合は、以下のように記述することができます。

<?php the_date('Y年m月j日', '<p class="post_date">', '</p>'); ?>

以下のように記述してしまうと、同じ日付が続く(公開日が同じ)場合、the_date() は何も出力しないので前後の p 要素だけがループ内で出力されてしまいます。

<p class="post_date"><?php the_date('Y年m月j日'); ?></p><!-- 良くない例 -->

get_the_date

現在の(または指定された)投稿や固定ページの公開(作成)日を取得します。

the_date() はループ内で複数の投稿を続けて出力する場合、直前の投稿と日付が同じであれば何も出力しませんが、get_the_date() は<?php echo get_the_date(); ?>と記述すれば、すべての投稿で日付を出力します。

但し、get_the_date() 自身は出力はしないので出力するには echo を使います。出力する際にエスケープ処理は必要ありません。

get_the_date( $d, $post )

パラメータ
  • $d(文字列):(オプション)時刻を表示するフォーマット。省略時は、管理画面「一般設定」の「日付フォーマット」(「設定」→「一般」で指定した書式)。
  • $post(整数 | オブジェクト):(オプション)投稿 ID または投稿オブジェクト。省略すると現在の投稿や固定ページ。
戻り値
指定された書式の日付の文字列
利用可能箇所
パラメータの投稿 ID または投稿オブジェクトを指定しない場合はループ内、指定する場合はどこでも可能。

以下は日付を p 要素でマークアップする例です。

the_date() は同じ日付が続く(公開日が同じ)場合、何も出力しませんが get_the_date() は echo を使えば全ての投稿で日付を出力することができます。

<p class="post_date"><?php echo get_the_date('Y年m月j日'); ?></p>

the_modified_time

投稿や固定ページが最後に更新された時刻 (と日付) を表示します。

the_modified_time( $d )

パラメータ
$d(文字列):(オプション)時刻を表示するフォーマット。省略時は、管理画面「一般設定」の「日付フォーマット」(「設定」→「一般」で指定した書式)。
戻り値
なし
利用可能箇所
ループ内

更新日時を表示する例

<p>更新日時: <?php the_modified_time('Y年n月j日(D)g時i分A'); ?></p>
<!-- (出力例)更新日時: 2019年4月15日(月)8時12分PM -->

get_the_modified_time

投稿や固定ページが最後に更新された時刻 (と日付) を取得します。

get_the_modified_time( $d, $post )

パラメータ
  • $d(文字列):(オプション)時刻を表示するフォーマット。省略時は、管理画面「一般設定」の「時刻フォーマット」(「設定」→「一般」で指定した書式)。
  • $post(整数 | オブジェクト):(オプション)投稿 ID または投稿オブジェクト。省略すると現在の投稿や固定ページ。
戻り値
指定された書式の時刻の文字列
利用可能箇所
パラメータの投稿 ID または投稿オブジェクトを指定しない場合はループ内、指定する場合はどこでも可能。

現在の投稿や固定ページの最終更新日時を表示する例。

<p>更新日時: <?php echo get_the_modified_time('Y年n月j日(D)g時i分A'); ?></p>

投稿 ID を指定して最終更新日時を表示する例。

<p>更新日時: <?php echo get_the_modified_time( 'Y年n月j日g時i分A', 148); ?></p>
<p>更新日時: <?php echo get_the_modified_time( 'Y年n月j日g時i分A', $post->ID); ?></p>

以下は、公開日時と更新日時を比較して同じでない場合のみ、更新日を表示する例です。

投稿や個別ページが一度も更新されていない場合は、更新日時は作成日時と同じになります。

引数に 'U' を指定してタイムスタンプを比較すると何故か更新していなくても値が1秒ずれてしまうので「年月日時分」の値で比較しています。

<?php
  if ( get_the_time('YmjGi') !== get_the_modified_time('YmjGi') ) {
    echo '<p>更新日:' .get_the_modified_time('Y年n月j日') .'</p>';
  }
?>

the_modified_date

投稿や固定ページが最後に更新された日付 (と時刻) を表示します。

the_modified_time() に似ていますが、パラメータとして表示する日付の前後に出力する文字をや取得するオプションを指定できます。

the_modified_date( $d, $before, $after, $echo )

パラメータ
  • $d(文字列):(オプション)日付を表示するフォーマット。省略時は、管理画面「一般設定」の「日付フォーマット」(「設定」→「一般」で指定した書式)。
  • $before(文字列):(オプション)投稿日の直前に出力するコードやテキスト
  • $after(文字列):(オプション)投稿日の直後に出力するコードやテキスト
  • $echo(真偽値):(オプション)投稿日を表示する場合は true(デフォルト)、表示しない(取得する)場合は false を指定
戻り値
出力する場合($echo が true)はなし、出力しない場合($echo が false)は結果の文字列
利用可能箇所
ループ内

更新した日付を出力する例

<?php the_modified_date( 'Y年m月j日', '<p class="update_date">更新日:', '</p>' ); ?>  

the_date() の場合とは異なり、以下でも同じです。

<p class="update_date">更新日:<?php the_modified_date( 'Y年m月j日' ); ?></p>

get_the_modified_date

投稿や固定ページが最後に更新された日付 (と時刻) を取得します。

get_the_modified_date( $d, $post )

パラメータ
  • $d(文字列):(オプション)時刻を表示するフォーマット。省略時は、管理画面「一般設定」の「日付フォーマット」(「設定」→「一般」で指定した書式)。
  • $post(整数 | オブジェクト):(オプション)投稿 ID または投稿オブジェクト。省略すると現在の投稿や固定ページ。
戻り値
指定された書式の日付の文字列
利用可能箇所
パラメータの投稿 ID または投稿オブジェクトを指定しない場合はループ内、指定する場合はどこでも可能。

以下は公開日と更新日を比較して更新されていれば(公開日と更新日が等しくない場合)更新日を表示し、そうでない場合は公開日(作成日)を表示する例です。

<?php
  if ( get_the_date('YmjGi') !== get_the_modified_date('YmjGi')  ) {
   the_modified_date( 'Y年m月j日', '<p class="update_date">更新日:', '</p>' );
  } else {
    echo '<p class="post_date">作成日:' .get_the_date( 'Y年m月j日') .'</p>';
    //the_date() を使うと同じ作成日時の場合、最初のみが表示される
  }
?>

以下のように get_the_time()get_the_modified_time() を使って比較しても、フォーマットに同じ値を指定すれば同じです。

<?php
  if ( get_the_time('YmjGi') !== get_the_modified_time('YmjGi') ) {
   the_modified_date( 'Y年m月j日', '<p class="update_date">更新日:', '</p>' );
  } else {
    echo '<p class="post_date">作成日:' .get_the_date( 'Y年m月j日') .'</p>';
  }
?>

以下は更新されていれば作成日と更新日を表示し、更新されていない(公開日と更新日が等しい)場合は作成日のみを表示する例です。

<?php
  if ( get_the_date('YmjGi') !== get_the_modified_date('YmjGi') ) {
    echo '<p class="post_date">作成日:' .get_the_date( 'Y年m月j日')
        .'<span class="update_date"> 更新日:'.get_the_modified_date( 'Y年m月j日')
        .'</span></p>';
  } else {
    echo '<p class="post_date">作成日:' .get_the_date( 'Y年m月j日') .'</p>';
  }
?>

カテゴリー

カテゴリーを出力したり取得するテンプレートタグ。

the_category

現在の記事が属するカテゴリーへのリンク(一覧)を表示します。

the_category( $separator, $parents, $post_id )

パラメータ
  • $separator(文字列):(オプション)個々のカテゴリー(親子関係を含む)を区切る文字列(セパレータ)。デフォルトは空の文字列で、ul/li 要素で一覧を出力。空の文字列以外を指定すると、ul/li 要素では囲まれず、個々のカテゴリーへのリンクの間に、セパレータの文字列が出力される。
  • $parents(文字列):(オプション)「親子」関係をどう表示するかの指定。デフォルトは空の文字列で親子関係を表示しない。以下のオプションを指定可能。
    • multiple:親と子のカテゴリーへのリンクを別々に表示
    • single:親のカテゴリーを表示するが子カテゴリーへのリンクで囲まれる
  • $post_id(整数):(オプション)カテゴリを取得したい投稿 ID。デフォルトは「false」(現在の投稿)
戻り値
なし
利用可能箇所
ループ内

パラメータを指定しない場合は、現在の投稿(記事)の属する全てのカテゴリーへのリンクが ul/li 要素で出力されます。

<?php the_category(); ?>

投稿が「お知らせ」「コラム」「音楽」のカテゴリーに属する場合は、以下のように出力されます。

<ul class="post-categories">
  <li><a href="http://localhost/category/news/" rel="category tag">お知らせ</a></li>
  <li><a href="http://localhost/category/column/" rel="category tag">コラム</a></li>
  <li><a href="http://localhost/category/music/" rel="category tag">音楽</a></li>
</ul>

第1パラメータのセパレータ文字列を指定すると、カテゴリーの一覧は「ul/li 要素」形式では出力されず、個々のリンクの間にセパレータの文字列が出力されます。

<?php the_category(' / '); ?>

投稿が「お知らせ」「コラム」「音楽」のカテゴリーに属する場合は、以下のように出力されます。

<a href="http://localhost/category/news/" rel="category tag">お知らせ</a> / 
<a href="http://localhost/category/column/" rel="category tag">コラム</a> / 
<a href="http://localhost/category/music/" rel="category tag">音楽</a>  

第2パラメータに「multiple」を指定すると親と子のカテゴリーへのリンクを別々に表示します。親カテゴリーと子カテゴリーのリンクの間には第1パラメータで指定したセパレータ文字列が出力されます。

<?php the_category(' &gt; ','multiple'); ?>

上記の場合、投稿が「音楽」と言う親カテゴリーを持つ「jazz」と言うカテゴリーに属する場合は以下のように出力されます。

<a href="http://localhost/category/music/">音楽</a> &gt; <a href="http://localhost/category/music/jazz/" rel="category tag">jazz</a>

第1パラメータに空文字を指定すれば「ul/li 要素」形式で出力されますが、親と子カテゴリーは1つの li 要素内に出力されます。

<?php the_category('','multiple'); ?>

上記の場合、投稿が「音楽」と言う親カテゴリーを持つ「jazz」と言うカテゴリーに属する場合は以下のように出力されます(親と子カテゴリーの間にセパレータは表示されない)。

<ul class="post-categories">
  <li>
    <a href="http://localhost/category/music/">音楽</a>
    <a href="http://localhost/category/music/jazz/" rel="category tag">jazz</a>
  </li>
</ul>

第2パラメータに「single」を指定すると親カテゴリーも表示されますが、リンクは子カテゴリーへのリンクになります。

<?php the_category(' &gt; ','single'); ?>

上記の場合、投稿が「音楽」と言う親カテゴリーを持つ「jazz」と言うカテゴリーに属する場合は以下のように出力されます。

<a href="http://localhost/category/music/jazz/" rel="category tag">音楽 &gt; jazz</a>

以下は the_category() のソースです。

function the_category( $separator = '', $parents = '', $post_id = false ) {
  echo get_the_category_list( $separator, $parents, $post_id );
}

get_the_category

投稿が属するカテゴリー情報(オブジェクト)を取得します。このタグはデフォルトのカテゴリーを取得します。 カスタムタクソノミー(カスタム分類)を取得する場合は get_the_terms() を使います。

get_the_category( $id )

パラメータ
$id(整数)(オプション): 投稿 ID。初期値: $post->ID (現在の投稿 ID)
戻り値
カテゴリーオブジェクトの配列
利用可能箇所
ループの外で使う場合は、パラメータとして投稿 ID を渡します。(投稿 ID を指定しない場合はループ内)

ループ内でパラメータを指定せずにこの関数を実行すると、現在処理中の投稿が属するカテゴリーオブジェクトが戻り値として返されます。

1つの投稿が複数のカテゴリーに属することもあるので、戻り値は配列になっています。

以下のように記述すると、投稿が属するカテゴリーオブジェクトを取得して配列変数 $cats に代入することができます。

<?php $cats = get_the_category(); ?> 

$cats はカテゴリーオブジェクトの配列なので、例えば最初のカテゴリーの名前を表示するには以下のように記述できます。

<?php 
  $cats = get_the_category();
  echo $cats[0]->name; // または echo $cats[0]->cat_name;
  //$cats[0] は最初のカテゴリーオブジェクト
?>

カテゴリーオブジェクトのプロパティ(メンバー変数)

カテゴリーのオブジェクトを変数 $cat に代入した場合、「$cat ->プロパティ名」でカテゴリーの各種のプロパティ(メンバー変数)にアクセスすることができます。

カテゴリーには以下のようなプロパティがあります。括弧内はエイリアス(別名)でどちらでも同じ値を取得できます。

プロパティ名 内容 データ型
term_id
(cat_ID)
カテゴリーのID 整数
name
(cat_name)
カテゴリーの名前 文字列
slug
(category_nicename)
カテゴリーのスラッグ 文字列
description
(category_description)
カテゴリーの説明 文字列
parent
(category_parent)
親カテゴリーの ID。親カテゴリーがない場合は「0」を返す 整数
count
(category_count)
そのカテゴリーに属する投稿数 整数
taxonomy タクソノミー名。カテゴリーの場合は必ず 'category' 文字列
term_group カテゴリーのグループ ID 整数
term_taxonomy_id カテゴリーのタクソノミー ID(カテゴリー ID ではない) 整数

※ term_id と term_taxonomy_id は同じ値になる場合がありますが、カテゴリー ID は term_id です。

取得したカテゴリーオブジェクトの内容(プロパティ)は var_dump() などで確認することができます。

<?php 
  $cats = get_the_category(); 
  var_dump($cats);
?> 

以下は、「お知らせ」と言うカテゴリーのみに属している投稿の場合の結果の例です。

array(1) {
  [0]=>
  object(WP_Term)#4814 (16) {
    ["term_id"]=>int(1)  //カテゴリーのID 1
    ["name"]=>string(12) "お知らせ"  //カテゴリー名
    ["slug"]=>string(4) "news"  //スラッグ
    ["term_group"]=>int(0)
    ["term_taxonomy_id"]=>int(1)
    ["taxonomy"]=>string(8) "category"
    ["description"]=>string(30) "サイトからのお知らせ"
    ["parent"]=>int(0)  //親カテゴリーなし
    ["count"]=>int(3)  //このカテゴリーに属する投稿数
    ["filter"]=>string(3) "raw"
    ["cat_ID"]=>int(1)
    ["category_count"]=>int(3)
    ["category_description"]=>string(30) "サイトからのお知らせ"
    ["cat_name"]=>string(12) "お知らせ"
    ["category_nicename"]=>string(4) "news"
    ["category_parent"]=>int(0)
  }
}

以下は上記の例のカテゴリー「お知らせ」の設定画面です。

カテゴリー「お知らせ」の設定画面のスクリーンショット

カテゴリーリンクに独自のクラスを追加

the_category() を使ったカテゴリーの出力では、リンク(a)要素の属性を操作することができませんが、get_the_category() を使うとカテゴリーのリンクにクラスやタイトルなどの属性を追加することができます。

以下は投稿の属する全てのカテゴリーのリンクに「cat-link-スラッグ」と言うクラスを指定して出力する関数の例です。ループ内で使用します。

functions.php に記述しておき、テンプレートでこの関数を呼び出します(1箇所だけで使用する場合は、直接テンプレートに記述して関数にはしないで echo すれば良いと思います)。

カテゴリーページの URL は get_category_link() を使って取得し、esc_url() を使ってエスケープ処理しています。

属性値への出力では esc_attr() でエスケープしています。カテゴリー名($cat->cat_name)は文字列しか設定できないので特にエスケープ処理はしていません。

function my_categories_with_class() {
  $cats = get_the_category();
  $separator = ' / ';  //区切り文字
  $output = '';
  if ( $cats ) {
    foreach($cats as $cat){
      $output .= '<a href="' 
      . esc_url( get_category_link( $cat->term_id ) ) 
      . '" class="cat-link-' . esc_attr($cat->slug)
      . '">' . $cat->cat_name . '</a>' . $separator;
    }
    echo trim( $output, $separator );  //最後の区切り文字を削除して出力
  }
}

投稿が「お知らせ(スラッグは news)」と「コラム(スラッグは column)」と言うカテゴリーの属している場合、以下のように出力されます。

追加されたクラスを利用してリンクのスタイル(文字色や背景色など)を設定することができます。

<a href="http://localhost/category/news/" class="cat-link-news">お知らせ</a> / 
<a href="http://localhost/category/column/" class="cat-link-column">コラム</a>

例えば、リンクの前にアイコンフォントを表示するには、以下のようにスタイルを設定します。(Font Awesome 5 を疑似要素で使う

.cat-link-news::before {
  content: "\f530 ";
  font-family: "Font Awesome 5 Free";
  font-weight: 900;
}
.cat-link-column::before {
  content: "\f001 ";
  font-family: "Font Awesome 5 Free";
  font-weight: 900;
}

以下は、クラス属性の他にタイトル属性とそのカテゴリーに属する投稿の数を表示する関数の例です。

function my_categories_with_class() {
  $cats = get_the_category();
  $separator = ' / ';
  $output = '';
  if ( $cats ) {
    foreach($cats as $cat){
      $output .= '<a href="' . esc_url( get_category_link( $cat->term_id ) ) 
      . '" title="' 
      . esc_attr( sprintf( "「%s」カテゴリーの全ての投稿を見る", $cat->name ) ) 
      . '" class="cat-link-' . esc_attr($cat->slug)
      . '">' . $cat->cat_name . '(' . $cat->count  .')</a>' . $separator;
    }
    echo trim( $output, $separator );
  }
}

以下は get_the_category() のソースです。

function get_the_category( $id = false ) {
  $categories = get_the_terms( $id, 'category' );
  if ( ! $categories || is_wp_error( $categories ) ) {
    $categories = array();
  }

  $categories = array_values( $categories );

  foreach ( array_keys( $categories ) as $key ) {
    _make_cat_compat( $categories[ $key ] );
  }

  /**
   * Filters the array of categories to return for a post.
   * @since 3.1.0
   * @since 4.4.0 Added `$id` parameter.
   * @param WP_Term[] $categories An array of categories to return for the post.
   * @param int|false $id         ID of the post.
   */
  return apply_filters( 'get_the_categories', $categories, $id );
}

特定のカテゴリーを取得(get_category_by_slug / get_category)

投稿が属する全てのカテゴリー(オブジェクト)ではなく、特定のカテゴリー(オブジェクト)を取得するには、get_category_by_slug() または get_category() を使います。

以下は、get_category_by_slug() を使ってスラッグが news のリンクを出力する例です。

<?php
  $cat = get_category_by_slug('news');
  $link = '<a href="' . esc_url( get_category_link( $cat->term_id ) ) . '">' . $cat->cat_name . '</a>' ;
  //スラッグが news のリンクを出力
  echo $link;
?>

以下は、get_category() を使ってカテゴリー名が「お知らせ」のリンクを出力する例です。

<?php
  $category_id = get_cat_ID( 'お知らせ' );
  $cat = get_category( $category_id );
  $link = '<a href="' . esc_url( get_category_link( $cat->term_id ) ) . '">' . $cat->cat_name . '</a>' ;
  //カテゴリー名が'お知らせ'のリンクを出力
  echo $link; 
?>

get_categories

パラメータで指定した条件のカテゴリー(オブジェクト)を取得します。

get_categories( $args )

パラメータ
$args(文字列|配列):(オプション)クエリ文字列形式または配列形式で指定。
戻り値
カテゴリーオブジェクトの配列
利用可能箇所
どこでも可能

パラメータの初期値(配列形式)

<?php 
$args = array(
  'type'         => 'post',
  'child_of'     => 0,
  'parent'       => '',
  'orderby'      => 'name',
  'order'        => 'ASC',
  'hide_empty'   => 1,
  'hierarchical' => 1,
  'exclude'      => '',
  'include'      => '',
  'number'       => '',
  'taxonomy'     => 'category',
  'pad_counts'   => false 
); 
?>
パラメータの連想配列
パラメータのキー
(値の型)

初期値
意味
child_of
(整数)
'child_of' => 1
初期値:0
指定したIDのカテゴリーより下の階層(子/孫など)のカテゴリーを全て取得。「'child_of' =>0」と指定すれば、ブログ内の全てのカテゴリーを取得。
parent
(整数)
'parent' => 1
初期値:なし
指定したIDのカテゴリーの直下にある階層のカテゴリーを全て取得。「'parent' =>0」と指定すれば、ブログ内の最上位の全てのカテゴリーを取得。
orderby
(文字列)
'orderby' => 'name'
初期値:name
指定したキーでカテゴリーを並び替える。id, slug, name, count, term_group のいずれかを指定。
order
(文字列)
'order' => 'desc'
初期値:asc
並べ替えの順序を次のいずれかで指定。'asc':昇順、'desc':降順
hide_empty
(論理値|整数)
'hide_empty' => 1
初期値:1
1(true)を指定した場合、投稿がないカテゴリーは取得しない。0(false)を指定すると、投稿のないカテゴリーも取得。
hierarchical
(論理値)
'hierarchical' => 1
初期値:1
「'hierarchical' => 1」を指定すると、空の子カテゴリーでも、空でない孫カテゴリーがあれば取得。
exclude
(文字列|配列)
'exclude' => '1,2,3'
初期値:なし
指定した ID のカテゴリーを除外して取得。child_of と組み合わせた場合、指定したカテゴリーにサブカテゴリーがあれば、それらも除外される。除外するカテゴリーの ID(term id)の配列またはコンマ(またはスペース)区切りの文字列で指定。
include
(文字列|配列)
'include' => '1,2,3'
初期値:なし
指定したIDのカテゴリーのみ取得。カテゴリーの ID(term id)の配列またはコンマ(またはスペース)区切りの文字列で指定。
number
(文字列|整数)
'number' => 5
初期値:なし
読み込むカテゴリーの数。
pad_counts
(論理値|整数)
'pad_counts' => 1
初期値:0
'pad_counts' => 1 と指定すると、親カテゴリーに子孫カテゴリーがある場合、親カテゴリーの投稿数は、すべての子孫カテゴリーの投稿数も含めた値になる。'pad_counts' => 0 と指定すると、親カテゴリーの投稿数には、子孫カテゴリーの投稿数は含まれない。
taxonomy
(文字列|配列)
'taxonomy' => 'category'
初期値:category
指定したタクソノミーから取得。
name
(文字列|配列)
'name' => 'お知らせ'
初期値:なし
カテゴリー名を文字列または配列で指定したカテゴリーを取得。
name__like
(文字列)
'name__like' => 'Word'
初期値:なし
カテゴリー名の先頭が、キーワードで指定した文字列で始まるカテゴリーを取得。
search
(文字列)
'search' => 'Word'
初期値:なし
カテゴリー名に、キーワードで指定した文字列を含んだカテゴリーを取得。
slug
(文字列|配列)
'slug' => 'WordPress'
初期値:なし
指定したスラッグのカテゴリーを取得。

WP_Term_Query

カテゴリーのスラッグが news と music のカテゴリーオブジェクトを取得する例。

<?php
  $cats = get_categories(array(
    'slug' => array('news','music'),
  ));   
?>

カテゴリーの名前が「お知らせ」と「音楽」のカテゴリーオブジェクトを取得する例。

<?php
  $cats = get_categories(array(
    'name' => array('お知らせ','音楽'),
  ));  
?>

最上位のカテゴリーを全て読み込み、名前順に並び替える例。

<?php
 $cats = get_categories(array(
  'parent' => 0,  //ブログ内の最上位の全てのカテゴリーを読み込む
  'hide_empty' => 0,  //記事のないカテゴリーも読み込む
  'orderby' => 'name'  //名前順で並び替える
));
?>

全てのカテゴリーのリンクを出力

以下は全てのカテゴリー(デフォルトの 'child_of' =>0)を投稿数の多い順で取得し、各アーカイブページへのリンクを出力する例です。

リンクの a 要素には cat-link-スラッグ と言うクラス属性を指定し、リンクには投稿数も表示します。

<?php
 $cats = get_categories(array(
  'orderby' => 'count',  //投稿数で並び替える
  'order' => 'desc'  //降順
));

if ( $cats ) {
  foreach($cats as $cat){
    $output .= '<li><a href="' 
    . esc_url( get_category_link( $cat->term_id ) ) 
    . '" class="cat-link-' . esc_attr($cat->slug)
    . '">' . $cat->cat_name 
    . '(' . $cat->count . ')</a></li>' ;
  }
  echo '<ul>'. $output . '</ul>'; 
}
?>

カテゴリー別の投稿一覧を出力

以下はトップページなどでカテゴリーごとの最新の投稿を表示する例です。

get_categories() でカテゴリーを読み込み、それぞれのカテゴリーに属する投稿を出力します。

通常のループでは、例えばトップページでは最新の投稿が取得されるので、特定のカテゴリーの投稿を読み込むにはサブループを使う必要があり、この例では WP_Query を使っています。

また、投稿が複数のカテゴリーに属している場合は、それぞれのカテゴリーに表示されます(結果としてそのページに複数回表示されます)。

<?php 
// 'parent' =>0 で最上位のカテゴリーを読み込む
$cats = get_categories( array('parent' =>0) );
// 読み込んだカテゴリーを1つずつ処理
foreach($cats as $cat):
?>
  <!-- カテゴリー名($cat->name)にアーカイブページへのリンクを設定 -->
  <h3><a href="<?php echo get_category_link($cat->term_id); ?>">
    <?php echo $cat->name; ?>
  </a></h3>
  <?php 
  // WP_Query のパラメータ cat にカテゴリーIDを渡してそのカテゴリーの投稿を読み込み
  $my_query = new WP_Query(array('cat'=>$cat->term_id));
  if ($my_query->have_posts()) :
  ?>
    <?php while ($my_query->have_posts()) : $my_query->the_post(); ?>
    <div>
      <h4><?php the_title(); ?></h4>
      <?php the_excerpt(); ?>
    </div>
    <?php endwhile; ?>
  <?php endif; ?>
  <?php wp_reset_postdata(); ?>
<?php endforeach; ?>

同じカテゴリーに属する投稿をを出力

投稿の個別ページにその投稿と同じカテゴリーに属する投稿の一覧をサイドバーなどのループの外に表示する例です。複数のカテゴリーに属している場合は、複数の一覧が表示されます。

投稿が属するカテゴリーは get_the_category() に投稿 ID を指定して取得できます。

但し、この場合ループの外なので get_the_ID() は使えないため get_queried_object() で現在表示しているページのオブジェクトを取得して、そのオブジェクトから ID を取得します。

カテゴリーに属する投稿を読み込むのにはサブループを使いますが、この例では get_posts() を使用しています。

また、以下の例では投稿の一覧には現在の投稿は表示しないようにしています。

<?php
// 現在表示しているページのオブジェクトを取得
$current_post = get_queried_object();
// 投稿が属するカテゴリーのオブジェクトを取得
$cats = get_the_category($current_post->ID);
// 読み込んだカテゴリーを1つずつ処理
foreach($cats as $cat):
?>
<h3>カテゴリー:
  <!-- カテゴリー名($cat->name)にアーカイブページへのリンクを設定 -->
  <a href="<?php echo get_category_link($cat->term_id); ?>">
    <?php echo $cat->name; ?>
  </a>の投稿
</h3>
<?php
  // get_posts のパラメータcategoryにカテゴリーIDを渡してそのカテゴリーの投稿を読み込み
  //パラメータは category でも cat でも可(get_posts の場合)
  $my_posts = get_posts(array('category' => $cat->term_id)); 
  // 読み込んだ投稿を1つずつ処理
  foreach($my_posts as $post) : setup_postdata($post);
  // もし投稿が現在の投稿と同じならスキップ
  if($post->ID === $current_post->ID) : continue;
  else:
?>
    <!-- 投稿のタイトルにリンクを設定 -->
    <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
  <?php endif; endforeach; ?>
</ul>
<?php wp_reset_postdata();  ?>
<?php endforeach; ?>

以下は get_categories() のソースです。

function get_categories( $args = '' ) {
  $defaults = array( 'taxonomy' => 'category' );
  $args     = wp_parse_args( $args, $defaults );

  $taxonomy = $args['taxonomy'];

  /**
   * Filters the taxonomy used to retrieve terms when calling get_categories().
   * @since 2.7.0
   * @param string $taxonomy Taxonomy to retrieve terms from.
   * @param array  $args     An array of arguments. See get_terms().
   */
  $taxonomy = apply_filters( 'get_categories_taxonomy', $taxonomy, $args );

  // Back compat
  if ( isset( $args['type'] ) && 'link' == $args['type'] ) {
    _deprecated_argument(
      __FUNCTION__,
      '3.0.0',
      /* translators: 1: "type => link", 2: "taxonomy => link_category" */
      sprintf(
        __( '%1$s is deprecated. Use %2$s instead.' ),
        '<code>type => link</code>',
        '<code>taxonomy => link_category</code>'
      )
    );
    $taxonomy = $args['taxonomy'] = 'link_category';
  }

  $categories = get_terms( $taxonomy, $args );

  if ( is_wp_error( $categories ) ) {
    $categories = array();
  } else {
    $categories = (array) $categories;
    foreach ( array_keys( $categories ) as $k ) {
      _make_cat_compat( $categories[ $k ] );
    }
  }

  return $categories;
}

タグ

タグを出力したり取得するテンプレートタグ。

the_tags

現在の記事に付けられたタグのアーカイブページへのリンクを表示します。 タグが付けられていない場合は何も表示しません。

the_tags( $before, $sep, $after )

パラメータ
  • $before(文字列):(オプション)タグ一覧の前に表示する文字列。初期値は タグ:
  • $sep(文字列):(オプション)各タグリンクの間に表示する文字列。初期値はコンマ(,)
  • $after(文字列):(オプション)最後のタグに続けて表示する文字列。初期値は空文字列
戻り値
なし
利用可能箇所
ループ内

以下は、タグ一覧の前に表示する文字列を「Tags: 」、セパレータを「 | 」として最後のタグに続けて <br> を出力する例です。

<?php the_tags( 'Tags: ', ' | ', '<br>' ); ?>

以下は、タグ一覧の前に font-awesome のアイコンを表示し、セパレータを半角スペース2つにして全体を p 要素で囲む例です。

<?php the_tags( '<p><i class="fas fa-tag"></i> ', ' &nbsp;', '</p>' ); ?>

以下は the_tags() のソースです。

function the_tags( $before = null, $sep = ', ', $after = '' ) {
  if ( null === $before ) {
    $before = __( 'Tags: ' );
  }

  $the_tags = get_the_tag_list( $before, $sep, $after );

  if ( ! is_wp_error( $the_tags ) ) {
    echo $the_tags;
  }
}

get_the_tags

投稿に付けられたタグ情報(オブジェクト)を取得します。

get_the_tags( $id )

パラメータ
$id(整数):(オプション) 投稿 ID。初期値は現在の投稿の ID
戻り値
タグオブジェクトの配列
利用可能箇所
パラメータの投稿 ID を指定しない場合はループ内(タグの ID を指定する場合はどこでも)

以下のように記述すると、投稿に付けられているタグオブジェクトを取得して配列変数 $tags に代入することができます。

$tags = get_the_tags();

$tags はタグオブジェクトの配列なので、例えば最初のタグの ID を表示するには以下のように記述できます。

<?php 
  $tags = get_the_tags();
  echo $tags[0]->term_id; // ;
  //$tags[0] は最初のタグオブジェクト
?>

タグオブジェクトのプロパティ(メンバー変数)

タグのオブジェクトを変数 $tag に代入した場合、「$tag ->プロパティ名」でタグの各種のプロパティ(メンバー変数)にアクセスすることができます。

タグオブジェクトには以下のようなプロパティがあります。

プロパティ名 内容 データ型
term_id タグのID 整数
name タグの名前 文字列
slug タグのスラッグ 文字列
description タグの説明 文字列
count そのタグに属する投稿数 整数
term_group タグのグループ ID 整数
term_taxonomy_id タグのタクソノミー ID(タグ ID ではない) 整数

取得したタグオブジェクトの内容(プロパティ)は var_dump() などで確認することができます。

<?php
  $tags = get_the_tags();
  var_dump($tags);
?>

以下は、「サンプル」と言うタグのみが付いている投稿の場合の結果の例です。

array(1) {
  [0]=>
  object(WP_Term)#4820 (10) {
    ["term_id"]=>int(6)  //タグのID 6
    ["name"]=>string(12) "サンプル"  //タグの名前
    ["slug"]=>string(6) "sample"  //タグのスラッグ
    ["term_group"]=>int(0)
    ["term_taxonomy_id"]=>int(6)
    ["taxonomy"]=>string(8) "post_tag"
    ["description"]=>string(33) "タグ「サンプル」の説明"  //タグの説明
    ["parent"]=>int(0)  // parent は常に 0
    ["count"]=>int(2)  //このタグに属する投稿数
    ["filter"]=>string(3) "raw"
  }
}

以下は上記の例のタグ「サンプル」の設定画面です。

タグ「サンプル」の設定画面のスクリーンショット

get_the_tags() で取得したタグオブジェクトの配列を使えば、出力する内容をカスタマイズすることができます(get_the_category() とほぼ同じような使い方になります)。

以下は投稿に付けられている全てのタグのリンクに「tag-link-スラッグ」と言うクラスを指定して出力する関数の例です。ループ内で使用します。

タグはカテゴリーとは異なり、投稿に付けられていない場合もあるので、必ず取得したオブジェクトの配列が存在するかを確認する必要があります。get_the_tags() はタグが存在しない場合、false を返します。

function my_tags_with_class() {
  $tags = get_the_tags();
  $separator = ' | ';
  $output = '';
  if ( $tags ) {  //タグが存在すれば
    foreach($tags as $tag){
      $output .= '<a href="' 
      . esc_url( get_tag_link( $tag->term_id ) ) 
      . '" class="tag-link-' . esc_attr($tag->slug)
      . '">' . $tag->name . '</a>' . $separator;
    }
    echo 'Tags: '. trim( $output, $separator );
  }
}

以下は、投稿に付けたタグを属する投稿が多い順に出力する関数の例です。タグ名の後に投稿の数を表示します。

PHP の usort() を使って投稿が多い順に並べ替えするために、別途比較関数を定義します。

function my_tags_sort_by_count() {
  $tags = get_the_tags(); //投稿に付けたタグを読み込み変数 $tags に代入
  $separator = ' | ';
  $output = '';
  
  if($tags) { //変数 $tags が false でなければ
    //タグの数を変数 $count に代入
    $count = count($tags); 
    //ユーザー定義の比較関数を使用して投稿が多い順にソート
    usort($tags, 'sort_tags_by_count'); 
    foreach($tags as $tag){
      //タグ名 $tag->name をリンク get_tag_link($tag->term_id) で囲み、投稿の数 $tag->count を表示
      $output .= '<a href="' . get_tag_link($tag->term_id) . ' ">' 
              . $tag->name . '(' . $tag->count . ')</a>'. $separator;
    }
    echo '<p>Tags: '. trim( $output, $separator ) .'</p>';
  }
}

//ユーザー定義の比較関数(投稿が多い順にソート)
function sort_tags_by_count($a, $b){
  if($a->count == $b->count) {
    return 0;
  }
  return ($a->count > $b->count) ? -1 : 1;
} 
usort()
ユーザー定義の比較関数を使用して、配列を値でソートする PHP の関数。
書式:usort ( array , cmp_function )
  • array :対象の配列
  • cmp_function :比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の数を返す必要があります。

以下は get_the_tags() のソースです。

function get_the_tags( $id = 0 ) {
 
  /**
   * Filters the array of tags for the given post.
   * @since 2.3.0
   * @see get_the_terms()
   * @param WP_Term[] $terms An array of tags for the given post.
   */
  return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
}