get_post_permalink()

get_post_permalink()とは？

get_post_permalink()は、
指定した投稿のパーマリンク（URL）を取得する関数
です。

似た関数に get_permalink() がありますが、get_post_permalink() は内部的にカスタム投稿タイプの特別なURL処理を行う場合があり、WordPressコアでは get_permalink() を呼び出すラッパー関数として実装されています。

実際には動作に大きな違いはありませんが、将来的な拡張性を考慮して分けられています。

get_post_permalink()の基本的な書式

get_post_permalink( int|WP_Post $id, bool $leavename = false, bool $sample = false )

get_post_permalink()の引数

get_post_permalink()の戻り値

文字列（URL）

get_permalink()との違い

混同しやすいので表で比較します。

WordPressコアではこう定義されています。

function get_post_permalink( $id = 0, $leavename = false, $sample = false ) {
    return get_permalink( $id, $leavename, $sample );
}

実際には get_permalink() と同じ関数が呼ばれています。

get_post_permalink()の基本的な使い方

投稿IDを指定

$url = get_post_permalink(42);
echo '<a href="' . esc_url($url) . '">投稿42へ</a>';

WP_Postオブジェクトを指定

$post = get_post(42);
$url = get_post_permalink($post);

下書きのサンプルパーマリンクを取得

下書きの編集画面では「サンプルURL」を表示する場合があります。

$url = get_post_permalink(42, false, true);

このとき、%postname%が残るURLが返ります。

$leavename の使い方

$leavenameをtrueにすると、スラッグの部分を%postname%のまま残したURLを取得します。

例:

$url = get_post_permalink(42, true);

出力:

https://example.com/%postname%/

これは管理画面で「スラッグを置き換えるため」に使うだけで、
通常のフロントエンドではほぼ使用しません。

カスタム投稿タイプとget_post_permalink()

カスタム投稿タイプを登録している場合も、この関数は正しいURLを返します。

例: bookというカスタム投稿タイプ

$book_id = 100;
$url = get_post_permalink($book_id);
echo '<a href="' . esc_url($url) . '">この本の詳細を見る</a>';

パーマリンク設定に応じて

https://example.com/book/サンプル本/

のように返ります。

クエリパラメータを追加する

URLを取得したあとに add_query_arg() でパラメータを追加できます。

$url = get_post_permalink(42);
$url_with_ref = add_query_arg('ref', 'newsletter', $url);

出力:

https://example.com/sample-post/?ref=newsletter

アンカーを付ける

$url = get_post_permalink(42) . '#comments';

HTMLに出力する

必ずesc_url()でサニタイズするのがベストプラクティスです。

<a href="<?php echo esc_url( get_post_permalink(42) ); ?>">リンク</a>

フィルターフック

内部では post_link フィルターを通ります。

例: 全投稿URLの末尾に「?source=custom」を付ける

add_filter('post_link', 'add_custom_ref', 10, 3);

function add_custom_ref($permalink, $post, $leavename) {
    return $permalink . '?source=custom';
}

get_permalink()との互換性

基本的にはほとんどのケースで get_permalink() を使って問題ありません。

get_post_permalink() は主に

• カスタム投稿タイプを多用する
• コアの拡張性を意識する
• 将来の変更に備える

といったケースで使います。

get_post_permalink()の実用例

投稿リンク付きタイトル

<h2>
  <a href="<?php echo esc_url( get_post_permalink($post->ID) ); ?>">
    <?php echo esc_html( get_the_title($post->ID) ); ?>
  </a>
</h2>

アイキャッチ画像リンク

<a href="<?php echo esc_url( get_post_permalink($post->ID) ); ?>">
  <?php echo get_the_post_thumbnail($post->ID, 'medium'); ?>
</a>

よくある質問

get_permalink()とどちらを使うべき？

ほとんどのテーマではget_permalink()で十分です。
両者は互換性があります。

ループ内で使う場合は？

$postを省略できます。

例:

while (have_posts()) {
  the_post();
  $url = get_post_permalink();
}

カスタム投稿でも動作する？

はい。カスタム投稿タイプでも正しいURLが生成されます。

下書きのサンプルURLはどう使う？

投稿が公開前の場合、管理画面の「パーマリンク設定表示」に使います。

まとめ

• get_post_permalink()は投稿ID・オブジェクトからパーマリンクを取得する関数
• 実質的にget_permalink()のラッパー
• $leavenameや$sampleで特殊なURLを取得可能
• カスタム投稿タイプにも対応
• esc_url()と組み合わせて安全に出力

ポイント

• 通常は get_permalink() で十分
• カスタム投稿など高度な場合に get_post_permalink() を使う
• URL加工は add_query_arg() と esc_url() を組み合わせる