WordPress ループで使うテンプレートタグや関数
WordPress のループでは WordPress がデータベースから取得した記事のデータから、テンプレートタグや関数を使ってその記事に関する情報を出力したり取得することができます。
以下はループで良く使うテンプレートタグの使い方などに関しての覚え書きです(ループの外で使うテンプレートタグやフックなどについても掲載しています)。
更新日:2022年04月06日
作成日: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 | 単独の & を & に変換 |
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; } }
single_month_title
月別アーカイブページで月・年名を出力または取得します。このタグは日付アーカイブページのみで動作し、カテゴリーアーカイブなど他のテンプレートでは動作しません。
single_month_title( $prefix, $display )
- パラメータ
-
- $prefix(文字列):(オプション)タイトルの前に配置するテキスト。指定すると「$prefix + 月 + $prefix + 年」のようなタイトルを生成します。初期値: なし
- $display(真偽値):(オプション)取得した値の処理方法。 true(初期値):日付(タイトル)を出力。 false:値として日付(タイトル)を返す。
- 戻り値
- なし(デフォルト)。第2パラメータ($display)に false を指定した場合は日付の文字列
- 利用可能箇所
- 日付アーカイブページ
日本語テンプレートの月別アーカイブページでパラメータなしで実行すると「1月2019」のような形式で出力されます。
<?php single_month_title(); ?> //1月2019 のような出力になります。
「1月2019」のような形式を変更することはできません(出力を変更できるフィルタもありません)。
月別アーカイブページで「2019年1月」のように出力するには、以下のようにすることができます。日付アーカイブページ以外では「0年0月 」のような表示になります。
日付アーカイブページでは $m, $year, $monthnum が利用可能です。
<?php if($m): ?> <?php echo substr($m, 0, 4). '年'. substr($m, 4, 2).'月'; ?> <?php else: ?> <?php echo $year . '年'. $monthnum.'月'; ?> <?php endif; ?>
または get_query_var() を使って単純に以下のように記述してもほぼ同じです。
<?php echo get_query_var('year').'年'.get_query_var('monthnum').'月'; ?>
get_the_time() や get_post_time() を使うと以下のように記述できます。
この場合はそのページの現在の投稿の公開日時から年月を取得しているので、日付アーカイブページ以外でも現在の投稿の公開日時の年月が表示されます(他の方法とは文脈上の違いがありますが)。
<?php echo get_the_time( 'Y年m月' ); ?> <!-- または --> <?php echo get_post_time( 'Y年m月' ); ?>
また、functions.php に以下のような独自の関数を作成して使用することもできます。
以下は single_month_title() のソースを元に作成した関数です。
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 = $my_year .'年' .$prefix .$my_month ; if ( !$display ) return $result; echo $result; }
作成した上記の関数を月別アーカイブページで記述します。
<?php single_month_title_jp(); ?> //2019年1月 のような出力になります。
以下は single_month_title() のソースです。
get_query_var() を使って月や年の日付の情報を取得しています。また、global $wp_locale の get_month() メソッドでその言語の月の表示(1月や2月など)を取得しています。
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; }
single_cat_title
カテゴリーのアーカイブで使用すると、カテゴリー名(タイトル)を出力または取得することができます。
single_cat_title( $prefix, $display )
- パラメータ
-
- $prefix(文字列):(オプション)タイトルの前に配置するテキスト。初期値: なし
- $display(真偽値):(オプション)取得した値の処理方法。 true(初期値):カテゴリー名(タイトル)を出力。 false:値としてカテゴリー名(タイトル)を返す。
- 戻り値
- ページタイトル(カテゴリー名)
- 利用可能箇所
- カテゴリーのアーカイブテンプレート(ループの外側)
以下の例は「カテゴリー:」に続けてカテゴリータイトル(カテゴリー名)を表示します。
<p><?php single_cat_title('カテゴリー:'); ?></p>
以下の例は「カテゴリー:xxxx(カテゴリータイトル) を表示中」と表示します。
<?php $cat_title = single_cat_title('カテゴリー:', false); echo $cat_title . ' を表示中' ; ?>
以下はカテゴリー別ページでそのカテゴリー ID を取得する例です。
$cat_name = single_cat_title( '', false); $cat_id = get_cat_ID($cat_name);
以下は single_cat_title() のソースです。
内部では single_term_title() を使用しています。
function single_cat_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); }
single_tag_title
タグのアーカイブで使用すると、タグ名(タイトル)を出力または取得することができます。
single_tag_title( $prefix, $display )
- パラメータ
-
- $prefix(文字列):(オプション)タイトルの前に配置するテキスト。初期値: なし
- $display(真偽値):(オプション)取得した値の処理方法。 true(初期値):タグ名(タイトル)を出力。 false:値としてタグ名(タイトル)を返す。
- 戻り値
- ページタイトル(タグ名)
- 利用可能箇所
- タグのアーカイブテンプレート(ループの外側)
以下の例は「タグ:」に続けてタグタイトル(タグ名)を表示します。
<p><?php single_tag_title('タグ:'); ?></p>
以下は single_tag_title () のソースです。
single_cat_title() 同様、内部では single_term_title() を使用しています。
function single_tag_title( $prefix = '', $display = true ) { return single_term_title( $prefix, $display ); }
日付/時刻
投稿の日付や時刻を出力するテンプレートタグ
the_time
投稿や固定ページの公開時刻を表示します。
パラメータを指定しない場合は、管理画面「一般設定」の「時刻フォーマット」(「設定」→「一般」)で指定した書式で表示されます。
デフォルトでは、投稿を公開した時刻だけが管理画面「一般設定」の「時刻フォーマット」で指定した書式で出力されます。
<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秒) からの秒数 |
以下は the_time() のソースです。
function the_time( $d = '' ) { /** * Filters the time a post was written for display. * @since 0.71 * @param string $get_the_time The formatted time. * @param string $d The time format. Accepts 'G', 'U', * or php date format. */ echo apply_filters( 'the_time', get_the_time( $d ), $d ); }
get_the_time
現在の(または指定された)投稿や固定ページの作成された時刻を指定したフォーマットで取得します。
get_the_time( $d, $post )
- パラメータ
- 戻り値
- 指定された書式の時刻の文字列
- 利用可能箇所
- パラメータの投稿 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 ); ?>
以下は get_the_time() のソースです。
function get_the_time( $d = '', $post = null ) { $post = get_post( $post ); if ( ! $post ) { return false; } if ( '' == $d ) { $the_time = get_post_time( get_option( 'time_format' ), false, $post, true ); } else { $the_time = get_post_time( $d, false, $post, true ); } /** * Filters the time a post was written. * @since 1.5.0 * @param string $the_time The formatted time. * @param string $d Format to use for retrieving the time the post was written. * Accepts 'G', 'U', or php date format value specified * in 'time_format' option. Default empty. * @param int|WP_Post $post WP_Post object or ID. */ return apply_filters( 'get_the_time', $the_time, $d, $post ); }
get_post_time
現在の投稿の公開日時を取得します。
get_post_time( $d, $gmt, $post, $translate )
- パラメータ
-
- $d(文字列) (オプション) 日時を表示するフォーマット。初期値: 'U' (UNIX タイムスタンプ)
- $gmt(真偽値) (オプション) true を指定すると GMT で日時を返します。初期値: false – ローカル時間帯
- $post(整数/オブジェクト) (オプション) 投稿の ID またはオブジェクト。 初期値: null(グローバルの $post オブジェクト)
- $translate(真偽値) (オプション) 日時の文字列を翻訳するかどうか。初期値: false(翻訳しない)
- 戻り値
- フォーマットした日時の文字列、または UNIX タイムスタンプ(整数)。失敗すると false。
- 利用可能箇所
- ループ内または投稿($post)を指定すればどこでも
以下は、現在の投稿の公開日時を表示する例です。第4パラメータの $translate を true にしないと曜日(D)が英語の表示になります。get_the_time() は内部でこの関数を使っています。
<?php echo get_post_time( 'Y年n月j日(D)g時i分A', false, null, true ); ?>
以下は get_post_time() のソースです。
投稿の post_date プロパティを取得後 mysql2date() で mysql から PHP の書式にフォーマットして get_post_time フィルタを適用して返しています。
function get_post_time( $d = 'U', $gmt = false, $post = null, $translate = false ) { $post = get_post( $post ); if ( ! $post ) { return false; } if ( $gmt ) { $time = $post->post_date_gmt; } else { $time = $post->post_date; } $time = mysql2date( $d, $time, $translate ); /** * Filters the localized time a post was written. * * @since 2.6.0 * * @param string $time The formatted time. * @param string $d Format to use for retrieving the time the post was written. * Accepts 'G', 'U', or php date format. Default 'U'. * @param bool $gmt Whether to retrieve the GMT time. Default false. */ return apply_filters( 'get_post_time', $time, $d, $gmt ); }
the_date
現在の投稿や固定ページの公開(作成)日を表示します。
ループ内で複数の投稿を続けて出力する場合、最初の記事の日付のみが表示され、直前の投稿と日付(公開日)が同じであれば何も出力しません。そのため投稿を日付ごとにまとめて出力する場合に適しています。
同じ日付を繰り返し表示するには echo と get_the_date() または the_time() を使用します。
the_date( $dt, $before, $after, $echo );
- パラメータ
- 戻り値
- 出力する場合($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 )
- パラメータ
- 戻り値
- 指定された書式の日付の文字列
- 利用可能箇所
- パラメータの投稿 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 )
- 戻り値
- なし
- 利用可能箇所
- ループ内
更新日時を表示する例
<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 )
- パラメータ
- 戻り値
- 指定された書式の時刻の文字列
- 利用可能箇所
- パラメータの投稿 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 )
- パラメータ
- 戻り値
- 出力する場合($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 )
- パラメータ
- 戻り値
- 指定された書式の日付の文字列
- 利用可能箇所
- パラメータの投稿 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>'; } ?>
get_month_link
指定した年・月の月別アーカイブページの URL を返します。年・月のパラメータに '' を指定すると、当月のアーカイブページの URL を返します
年別のアーカイブページの URL は get_year_link() で、日別のアーカイブページの URL は get_day_link() で取得できます。
get_month_link( $year, $month )
- パラメータ
-
- $year(真偽値/整数):(必須)取得するアーカイブページ URL の年。今年を指定するには '' または false を指定。
- $month(真偽値/整数):(必須)取得するアーカイブページ URL の月。今月を指定するには '' または false を指定。
- 戻り値
- 指定した年・月の月別アーカイブページの URL。
- 利用可能箇所
- どこでも。プラグインやテーマでは、setup_theme アクションの呼び出し以降に使用します。それより早く(plugins_loaded を含む)使用すると Fatal エラーを起こします。
以下は今月の月別アーカイブページのリンクを表示する例です。
<a href="<?php echo get_month_link( '', '' ); ?>">今月の投稿一覧</a>
以下は2019年1月のアーカイブページの URL を取得する例です。
<?php $url_201901 = get_month_link( '2019', '1' ); ?>
以下はその投稿が書かれた(公開された)月の月別アーカイブページのリンクを表示する例です。
投稿が書かれた年と月は get_the_time() や get_the_date() などを使って取得することができます。
<?php $post_year = get_the_time( 'Y' ); $post_month = get_the_time( 'm' ); $post_ym = get_the_time( 'Y年m月' ); ?> <a href="<?php echo get_month_link( $post_year, $post_month ); ?>"><?php echo $post_ym; ?>のアーカイブ</a>
以下は get_month_link() のソースです。
function get_month_link( $year, $month ) { global $wp_rewrite; if ( ! $year ) { $year = current_time( 'Y' ); } if ( ! $month ) { $month = current_time( 'm' ); } $monthlink = $wp_rewrite->get_month_permastruct(); if ( ! empty( $monthlink ) ) { $monthlink = str_replace( '%year%', $year, $monthlink ); $monthlink = str_replace( '%monthnum%', zeroise( intval( $month ), 2 ), $monthlink ); $monthlink = home_url( user_trailingslashit( $monthlink, 'month' ) ); } else { $monthlink = home_url( '?m=' . $year . zeroise( $month, 2 ) ); } /** * Filters the month archive permalink. * @since 1.5.0 * @param string $monthlink Permalink for the month archive. * @param int $year Year for the archive. * @param int $month The month for the archive. */ return apply_filters( 'month_link', $monthlink, $year, $month ); }
current_time
ブログの現在のローカル時間を、MySQL タイムスタンプまたは Unix タイムスタンプまたは PHP の日付フォーマットのいずれかの形式で返します。
current_time($type, $gmt)
- パラメータ
-
- $type(文字列):(必須)取得する時刻の形式。以下の何れか
- mysql
- timestamp
- その他の文字は PHP の日付フォーマットと解釈される
- $gmt(整数|真偽値):(オプション)取得する時刻のタイムゾーン (ローカルまたは GMT)。初期値:false(0)ローカル。
- $type(文字列):(必須)取得する時刻の形式。以下の何れか
- 戻り値
- $type が timestamp の場合は整数のタイムスタンプ、それ以外は時刻を表す文字列。パラメータ $gmt に 1 を指定した場合、GMT 時刻の値。0 を指定または省略した場合、管理画面の一般設定ページで指定されたタイムゾーンのローカルタイム。
- 利用可能箇所
- どこでも
第1パラメータ $type の指定により以下のよう形式で値を取得します。
<?php echo current_time('mysql'); //2019-06-27 15:26:04 echo current_time('timestamp'); //1561649202 echo current_time('Y年n月j日(D)g時i分A'); //2019年6月27日(Thu)3時26分PM ?>
以下はパラメータに mysql を指定して MySQL の形式で値を取得してそれを preg_split() で分割し変数に格納する例です。
<?php $blogtime = current_time('mysql'); list( $ct_year, $ct_month, $ct_day, $hour, $minute, $second ) = preg_split( '([^0-9])', $blogtime ); ?> <a href="<?php echo get_year_link($ct_year); ?>">今年のアーカイブ</a> <a href="<?php echo get_month_link($ct_year, $ct_month); ?>">今月のアーカイブ</a> <a href="<?php echo get_day_link($ct_year, $ct_month, $ct_day); ?>">今日のアーカイブ</a>
以下は current_time() のソースです。
function current_time( $type, $gmt = 0 ) { switch ( $type ) { case 'mysql': return ( $gmt ) ? gmdate( 'Y-m-d H:i:s' ) : gmdate( 'Y-m-d H:i:s', ( time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) ) ); case 'timestamp': return ( $gmt ) ? time() : time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ); default: return ( $gmt ) ? gmdate( $type ) : gmdate( $type, time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) ); } }
パーマリンク
the_permalink
現在ループの中で処理されている投稿のパーマリンクの URL(アドレス)を表示(出力)します。
投稿 ID を与えて他の投稿のパーマリンクを取得する場合は、get_permalink() を使います。
the_permalink( $post )
- パラメータ
- $post (int|WP_Post) :(オプション)投稿または固定ページの整数型の ID、または投稿オブジェクト。初期値:global $post (ver 4.4.0でパラメータ $post が追加されました)
- 戻り値
- なし
- 利用可能箇所
- WordPress ループ内
個々の投稿のページにはアドレス(パーマリンク)が割り振られていて、このテンプレートタグを使用するとそのページのアドレス(記事のリンク)を出力することができます。
以下は、投稿のタイトルを出力し、該当するページへリンクする例です。
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
この関数は以下のように「wp-includes/link-template.php」で定義されています。
出力はエスケープ処理され、'the_permalink' フィルターが設置されています。
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 $postPost ID, WP_Post object, or 0. Default 0. */ echo esc_url( apply_filters( 'the_permalink', get_permalink( $post ), $post ) ); }
get_permalink
投稿または固定ページのパーマリンク(アドレス URL)を取得します。
現在の投稿情報(グローバル変数 $post)または指定した投稿情報(オブジェクト)のパーマリンク URL を取得します。
get_permalink() のエイリアスで get_the_permalink() という関数もあります。
get_permalink( $post, $leavename )
- パラメータ
-
- $post(int|WP_Post):(オプション) 投稿または固定ページの整数型の ID、または投稿オブジェクト (初期値: ループ内で使用した場合、表示中の投稿の ID。それ以外の場合は、グローバル変数 $post)
- $leavename(bool):(オプション) 投稿名あるいは固定ページ名(%postname%)を保持するかどうか。true の場合、実際の URI ではなく構造的なリンクを返します。 例: http://www.example.com/my-post ではなく http://www.example.com/%postname%(初期値: false)
- 戻り値
- パーマリンクの URL。ページが存在しない場合は false。
- 利用可能箇所
- パラメータの ID を指定せずに一覧ページ(インデックスやアーカイブなど)のループの外側で使用した場合、現在の表示しているページのパーマリンクではなく、ループの一番最後の投稿の URL を返します。
※ get_permalink() で取得した値を出力する場合は適切にエスケープ処理を行う必要があります。
get_the_ID() を使ってパラメーター $post に表示中のページの ID を指定する例
<?php echo esc_url( get_permalink( get_the_ID() ) ); ?> //出力例 http://www.example.com/my-post
パラメーター $leavename に true を指定する例
<?php echo esc_url( get_permalink( get_the_ID(), true ) ); ?> //出力例 http://www.example.com/%postname%
以下は、the_title() と get_permalink() を使ってタイトルにリンクを付けて h2 要素で出力する例です。
the_title() は第一引数と第二引数にタイトルの前後に配置するテキスト(文字列)を指定することができます。この場合、引数に文字列として指定するので the_permalink() は使えず get_permalink() を使いますがエスケープ処理が必要になります。
<?php the_title( '<h2><a href="' . esc_url( get_permalink() ) . '">', '</a></h2>' ); ?>
以下のような出力になります。
<h2><a href="http://example.com/xxxx/xxxx/">タイトル</a></h2>
以下は、excerpt_more と言うフィルタフックを使って、抜粋の文字数が最大値を超える場合に抜粋の後に省略記号の代わりに[続きを読む]と言うリンクを挿入する例です。
function my_excerpt_more( $more ) { return '<a href="' . esc_url( get_permalink() ) . '">[続きを読む]</a>'; } add_filter( 'excerpt_more', 'my_excerpt_more' );
the_permalink() と get_permalink()
the_permalink() の定義(ソース)を確認すると以下のようになっています。
function the_permalink( $post = 0 ) { echo esc_url( apply_filters( 'the_permalink', get_permalink( $post ), $post ) ); }
get_permalink() で取得した値に「the_permalink」フィルターフックを適用して、esc_url() でエスケープ処理後に出力されています。
もし、the_permalink() で出力される値と全く同じ値を取得する(フィルターも考慮する)場合は、以下のようになります。
$permalink_value = esc_url( apply_filters( 'the_permalink', get_permalink() ) );
カテゴリー
カテゴリーを出力したり取得するテンプレートタグ。
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(' > ','multiple'); ?>
上記の場合、投稿が「音楽」と言う親カテゴリーを持つ「jazz」と言うカテゴリーに属する場合は以下のように出力されます。
<a href="http://localhost/category/music/">音楽</a> > <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(' > ','single'); ?>
上記の場合、投稿が「音楽」と言う親カテゴリーを持つ「jazz」と言うカテゴリーに属する場合は以下のように出力されます。
<a href="http://localhost/category/music/jazz/" rel="category tag">音楽 > 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() を使います。
投稿に関係なく指定した ID のカテゴリーオブジェクトを取得するには get_category() を使います。
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() のソースです。
内部では get_the_terms() を使っています。
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_by_slug( $slug )
- パラメータ
- $slug(文字列):(必須)カテゴリーのスラッグ
- 戻り値
- カテゴリーのオブジェクト。見つからない場合は false
- 利用可能箇所
- どこでも
以下は、get_category_by_slug() を使ってスラッグが news のリンクを出力する例です。
変数 $cat にはカテゴリーオブジェクトが取得されているので、そのプロパティからカテゴリー ID($cat->cat_ID)やカテゴリー名($cat->cat_name)を取得することができます。
<?php $cat = get_category_by_slug('news'); $cat_id = $cat->cat_ID; $cat_name = $cat->cat_name; $link = '<a href="' .esc_url(get_category_link($cat_id)). '">' .$cat_name. '</a>' ; //スラッグが news のリンクを出力 echo $link; ?>
カテゴリー ID は $cat->term_id、カテゴリー名は $cat->name でも取得できます(カテゴリーオブジェクトのプロパティ)。
<?php $cat = get_category_by_slug('news'); $link = '<a href="' . esc_url( get_category_link( $cat->term_id ) ) . '">' . $cat->name . '</a>' ; echo $link; ?>
以下は get_category_by_slug() のソースです。
内部では get_term_by() を使っています。
function get_category_by_slug( $slug ) { $category = get_term_by( 'slug', $slug, 'category' ); if ( $category ) { _make_cat_compat( $category ); } return $category; }
get_category
カテゴリー ID またはカテゴリーオブジェクトを指定して、カテゴリーの情報(オブジェクト)を取得します。
get_category( $category, $output, $filter )
- パラメータ
-
- $category(整数|オブジェクト):(必須)カテゴリー ID またはカテゴリーオブジェクト
- $output(定数の文字列):(オプション) 戻り値の型示す定数 OBJECT, ARRAY_A, ARRAY_N の何れか(省略時は OBJECT)
- OBJECT:オブジェクト
- ARRAY_A:連想配列。(連想配列のキーがオブジェクトのプロパティ名)
- ARRAY_N:通常の配列
- $filter(文字列):(オプション) 無害化のコンテキスト(フィルター名)。初期値:'raw'
- 'raw':数値フィールドの値のみ無害化
- 'edit':各種フィルターフックで無害化
- 'db':各種フィルターフックで無害化
- 'display':各種フィルターフックで無害化
- 戻り値
- $output で指定された型のカテゴリーオブジェクト。$category が存在しない場合は false。
- 利用可能箇所
- どこでも
以下は、カテゴリー名が「音楽」の投稿が1つ以上あればリンクを出力する例です。
そのカテゴリーに属する投稿数は get_category( $category_id )->category_count で取得できます(カテゴリーオブジェクトのプロパティ)。
<?php $cat_name = '音楽'; $category_id = get_cat_ID( $cat_name ); $link = '<a href="' . esc_url( get_category_link( $category_id ) ) . '">' . $cat_name . '</a>' ; if ( get_category( $category_id )->category_count > 0 ) { echo $link; } ?>
以下は get_category() のソースです。
内部では get_term() を使っています。
function get_category( $category, $output = OBJECT, $filter = 'raw' ) { $category = get_term( $category, 'category', $output, $filter ); if ( is_wp_error( $category ) ) { return $category; } _make_cat_compat( $category ); return $category; }
get_category_link
指定したカテゴリーの一覧(アーカイブ)ページのリンクアドレス(URL)を取得する関数です。
get_category_link( $category )
- パラメータ
- $category(整数|オブジェクト):(必須)カテゴリー ID またはカテゴリーオブジェクト
- 戻り値
- カテゴリーアーカイブページへのリンクの URL。指定したカテゴリーが存在しない場合は空の文字列。
- 利用可能箇所
- どこでも可能
以下はカテゴリー名から get_cat_ID() を使ってカテゴリー ID を取得して、get_category_link() でカテゴリーページの URL を取得する例です。
URL を href 属性へ出力する際は、esc_url() を使ってエスケープ処理しています。
<?php //カテゴリー名を変数に代入 $my_cat_name = 'お知らせ'; // カテゴリー名から ID を取得 $category_id = get_cat_ID( $my_cat_name ); // カテゴリー ID から URL を取得 $category_link = get_category_link( $category_id ); ?> <!-- カテゴリーページへのリンクを出力 --> <a href="<?php echo esc_url( $category_link ); ?>" title="<?php echo $my_cat_name; ?>"> <?php echo $my_cat_name; ?> </a>
以下は get_category_link() のソースです。
内部では get_term_link() を使用しています。
function get_category_link( $category ) { if ( ! is_object( $category ) ) { $category = (int) $category; } $category = get_term_link( $category ); if ( is_wp_error( $category ) ) { return ''; } return $category; }
get_categories
パラメータで指定した条件のカテゴリー(オブジェクト)を取得します。
get_categories( $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' 初期値:なし |
指定したスラッグのカテゴリーを取得。 |
カテゴリーのスラッグが 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; }
get_cat_name
カテゴリーのIDから、カテゴリーの名前を取得します。
get_cat_name( $cat_id )
- パラメータ
- $cat_id(整数):(必須)カテゴリーID
- 戻り値
- カテゴリー名
- 利用可能箇所
- どこでも
以下はカテゴリー ID が 1 のカテゴリーの名前を出力する例です。
<?php echo get_cat_name(1);?>
以下は get_cat_name() のソースです。
get_term() でタームオブジェクトを取得し、そのプロパティ name からカテゴリー名を取得しています。
function get_cat_name( $cat_id ) { $cat_id = (int) $cat_id; $category = get_term( $cat_id, 'category' ); if ( ! $category || is_wp_error( $category ) ) { return ''; } return $category->name; }
get_cat_ID
カテゴリー名からカテゴリーIDを取得します。
get_cat_ID( $cat_name )
- パラメータ
- $cat_name(文字列):(必須)カテゴリー名を指定。
- 戻り値
- カテゴリーID。カテゴリー名が見つからなかった場合は0。
- 利用可能箇所
- どこでも可能
以下は「お知らせ」というカテゴリー名のカテゴリー ID を取得する例です。
<?php $cat_id = get_cat_ID('お知らせ'); ?>
以下は get_cat_ID() のソースです。
get_term_by() を使ってタクソノミー名に category を指定してタームオブジェクトを取得し、ターム ID を取得しています。
正確には第1パラメータに name を指定しているので、第2パラメータにはターム名(この場合はカテゴリー名)を指定し、第3パラメータにはタクソノミー名(この場合は category)を指定しています。
function get_cat_ID( $cat_name ) { $cat = get_term_by( 'name', $cat_name, 'category' ); if ( $cat ) { return $cat->term_id; } return 0; }