WordPressのURL・パス取得｜画像やCSSで使う関数の使い分け

この記事でわかること
• テーマ内の画像やファイルを、環境に左右されないURLで表示できる
• 固定ページ・記事・一覧ページへのリンクを、目的に合った関数で書き分けられる
• URLを出力するときのセキュリティ対策を、迷わず入れられる

WordPressのテーマを作ると、画像のパスやページへのリンクを書く場面が何度も出てきます。URLを直接書くと、サイトを移行したときにリンク切れの原因になります。関数で出力する方法を覚えれば、環境が変わっても壊れにくいテーマを作れます。

URL・パス取得関数の全体像

最初に、どの関数にも共通する出力のルールを確認します。そのうえで、テーマ内のファイルを参照する方法、サイト内のページへリンクする方法の順に進みます。共通ルールを知らないと後半のコードが読みにくくなるため、初めての人は目次の順に読んでください。

やりたいことが決まっている場合は、次の表から使う関数と解説している箇所を探してください。

関数でURLを出力する基本ルール

個別の関数に入る前に、すべての関数に関わる2つのルールを押さえます。echoが必要かどうかの判断と、出力時の安全対策です。

表示するthe_、値を返すget_

この記事で扱う関数は、名前の頭で動きが分かれます。the_で始まる関数はその場で表示し、get_で始まる関数は値を返すだけです。

get_で始まる関数にechoを付け忘れると、何も表示されません。関数名だけで判断しにくいときは、公式リファレンスの戻り値（Return）の欄で確認できます。

esc_url()でURLを安全に出力する

esc_url()は、URLを検査・整形してから出力するための関数です。不正なスクリプトを埋め込まれるXSS※1を防ぐ目的で使います。

<?php echo esc_url( $url ); ?>  <!-- URLを検査・整形して出力 -->

WordPress公式は、src属性やhref属性を含むすべてのURL出力にesc_url()を使うよう推奨しています。詳しくはWordPress公式（Escaping Data）で確認できます。

迷ったときは、次のように覚えると判断しやすくなります。

※1：XSS…Webページに不正なスクリプトを埋め込み、閲覧者の環境で実行させる攻撃のこと。

テーマ内の画像・ファイルを参照する

テーマフォルダに置いた画像やCSS、JavaScriptを読み込むには、テーマのURLを取得する関数を使います。基本の書き方と、変数に入れて使い回す書き方を紹介します。

get_template_directory_uri()でテーマのURLを取得する

get_template_directory_uri()は、有効化しているテーマのフォルダのURLを返す関数です。値を返すだけなので、表示するにはechoが必要です。

<?php echo esc_url( get_template_directory_uri() ); ?>  <!-- https://example.com/wp-content/themes/テーマ名 -->

返ってくるURLの末尾には、スラッシュが付きません。そのため、後ろにつなげるパスは/img/〜のようにスラッシュから書き始めます。

<img src="<?php echo esc_url( get_template_directory_uri() . '/img/sample.png' ); ?>" alt="">  <!-- テーマ内のimgフォルダの画像 -->

子テーマを使っている場合、この関数は親テーマのURLを返します。子テーマ側のファイルを参照したいときは、get_stylesheet_directory_uri()という別の関数を使います。

変数に入れて使い回す

同じテンプレート内で何度もテーマのURLを使う場合は、戻り値を変数に入れておくと記述が短くなります。

<?php $theme_uri = get_template_directory_uri(); ?>                          <!-- 変数に格納 -->
<img src="<?php echo esc_url( $theme_uri . '/img/logo.png' ); ?>" alt="">    <!-- 出力時にエスケープ -->
<img src="<?php echo esc_url( $theme_uri . '/img/sample.png' ); ?>" alt="">  <!-- 出力時にエスケープ -->

ポイントは、変数に入れるときではなく出力する直前にesc_url()で囲むことです。WordPress公式も、エスケープは出力の直前に行う書き方を推奨しています。

サイト内のページにリンクする

サイト内のリンクは、リンク先の種類によって使う関数が変わります。固定のパス、記事、投稿タイプの一覧ページの順に見ていきます。

home_url()で固定のパスへリンクする

home_url()は、サイトのトップURLを返す関数です。管理画面の「設定」＞「一般」にある「サイトアドレス」の値が使われます。

引数にパスを渡すと、トップURLの後ろに連結されます。SSL環境では、自動でhttpsのURLになります。

<a href="<?php echo esc_url( home_url( '/sample-page/' ) ); ?>">サンプルページ</a>  <!-- https://example.com/sample-page/ へのリンク -->

ドメインを直接書かないため、テスト環境から本番環境へ移行してもリンクが壊れにくくなります。お問い合わせページや会社概要ページなど、URLが決まっているページへのリンクに向いています。

the_permalink()で一覧から記事へリンクする

the_permalink()は、現在の投稿のURL（パーマリンク）を表示する関数です。表示まで行うので、echoは必要ありません。

<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>  <!-- 記事タイトルを記事ページへのリンクにする -->

関数の内部でesc_url()を通しているため、外側で囲む必要もありません。

この関数はループ※2の中で使う前提です。記事一覧のループ内に書くと、各記事の詳細ページへのリンクになります。

※2：ループ…WordPressで、投稿を1件ずつ取り出して表示する仕組み。

ループの基本の書き方

ループは、テンプレートファイルで投稿を出力するためのWordPressの標準の仕組みです。取得した投稿を1件ずつ順に処理し、ループの中に書いたHTMLやPHPを投稿ごとに実行します。

次のコードは、記事タイトルを並べて、それぞれを記事ページへのリンクにする例です。

<?php if ( have_posts() ) : ?>                                     <!-- ① -->
  <?php while ( have_posts() ) : the_post(); ?>                    <!-- ② -->
    <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>  <!-- ③ -->
  <?php endwhile; ?>
<?php endif; ?>

ループは必ずifとwhileで始め、endwhileとendifで閉じます。the_permalink()やthe_title()は、この開始と終了の間に書きます。

表示される件数は、管理画面の「設定」＞「表示設定」にある「1ページに表示する最大投稿数」で決まります。投稿がないときのメッセージは、endwhileとendifの間にelseを書いて出力できます。

get_permalink()で特定の記事へリンクする

get_permalink()は、投稿IDを渡してその記事のURLを返す関数です。値を返すだけなので、echo esc_url()で囲んで出力します。

<a href="<?php echo esc_url( get_permalink( 123 ) ); ?>">記事タイトル</a>  <!-- 投稿ID 123 の記事へのリンク -->

一覧ページのループの外でIDを指定せずに使うと、ループで最後に表示した記事のURLが返ります。ループの外では、必ずIDを指定しましょう。

なお、get_the_permalink()はget_permalink()の別名で、中身は同じです。

the_permalink()とget_permalink()の使い分け

get_post_type_archive_link()で投稿タイプの一覧へリンクする

get_post_type_archive_link()は、投稿タイプ名を渡すと、その一覧（アーカイブ）ページのURLを返す関数です。お知らせや制作実績など、カスタム投稿タイプの一覧へリンクするときに使います。

<a href="<?php echo esc_url( get_post_type_archive_link( 'news' ) ); ?>">お知らせ一覧</a>  <!-- 投稿タイプ news の一覧ページへのリンク -->

投稿タイプを登録するときに'has_archive' => trueを設定していないと、falseが返ります。リンクが空になる場合は、まずこの設定を確認しましょう。

通常の投稿を表す'post'を渡した場合は、投稿ページの設定があればそのURLが返ります。設定がなければ、サイトのトップURLが返ります。

さいごに

まとめ

テーマ制作でURLを出力するときは、リンク先の種類に合わせて関数を選びます。まずは次の3つを押さえておけば、多くの場面に対応できます。

• テーマ内の画像はget_template_directory_uri()に、スラッシュから始まるパスをつなげる
• リンクは、固定のパスならhome_url()、記事ならthe_permalink()かget_permalink()を使う
• get_で取得したURLは、出力の直前にesc_url()で囲む

よくある質問

the_permalink()にもesc_url()を付けるべき？

付ける必要はありません。the_permalink()は、関数の内部でesc_url()を通してから表示しています。

テーマの画像が表示されません

get_template_directory_uri()の戻り値は、末尾にスラッシュが付きません。つなげるパスが/img/〜のようにスラッシュから始まっているか確認しましょう。

子テーマに置いた画像が表示されません

子テーマを使っている場合、get_template_directory_uri()は親テーマのURLを返します。子テーマ側のファイルを参照するときは、get_stylesheet_directory_uri()を使います。

一覧ページでget_permalink()が別の記事のURLを返します

ループの外でIDを指定せずに使うと、ループで最後に表示した記事のURLが返ります。ループの外では、get_permalink()に投稿IDを渡しましょう。

get_post_type_archive_link()のリンクが空になります

投稿タイプの登録時に、'has_archive' => trueが設定されているか確認しましょう。設定がないと、関数はfalseを返します。