post_permalink()

post_permalink()とは？

まずポイントからお伝えします。

post_permalink()はWordPressコアに存在する正式な関数です。

ただし注意点として、

• ほとんどのケースでは get_permalink() の代用や内部利用のために存在する
• テーマやプラグインでは直接使うことは少ない

という特徴があります。

つまり、「過去の互換性」や「内部用途」のために残っている側面が大きい関数です。

post_permalink()の基本的な書式

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

post_permalink()の引数

post_permalink()の戻り値

文字列（URL）

post_permalink()の使い方の例

基本的に get_permalink() と同じ感覚で使えます。

投稿IDを指定する

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

WP_Postオブジェクトを指定する

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

$leavenameをtrueにする

$url = post_permalink(42, true);

結果例：

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

$sampleをtrueにする

下書き状態の投稿のサンプルURLを取得します。

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

このパターンは主に管理画面で使われます。

内部の実装

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

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

つまり、get_permalink()をそのまま呼ぶだけのラッパー関数です。

では、なぜ存在するのか？

歴史的経緯が理由です。

WordPressの古いバージョンではパーマリンクの取得に関して関数が分かれており、

• post_permalink() は投稿用
• page_link() は固定ページ用

といった使い分けをしていました。

しかし、現在は**get_permalink()だけで全投稿タイプに対応するため、
post_permalink()は事実上後方互換性を保つために残っている**だけです。

get_permalink()との違い

違いは全くありません。

カスタム投稿タイプでは？

post_permalink()を使っても問題なく正しいURLが生成されます。

例：

$custom_post_id = 123;
$url = post_permalink($custom_post_id);

「book」「movie」といったカスタム投稿でも同じです。

フィルターフック

post_permalink()を使っても内部でpost_linkフィルターが呼ばれます。

例：

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

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

post_permalink()のよくある使い方

正直にいえば、最近の開発ではget_permalink()を使うほうが一般的です。

ただ、古いテーマやプラグインのコードには次のように使われていることがあります。

アイキャッチ画像リンク

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

タイトルリンク

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

post_permalink()のよくある質問

get_permalink()との違いは？

違いはありません。完全に同じ動作をします。

新しいテーマでは使うべき？

新規開発ではget_permalink()を推奨します。

カスタム投稿タイプでも使える？

はい、問題なく使えます。

将来的に廃止される？

WordPressコアでは後方互換性を重視するため、すぐに廃止されることは考えにくいですが、新しい開発ではget_permalink()を使うのがベストプラクティスです。

post_permalink()のまとめ

• post_permalink()は指定投稿のURLを取得する関数
• 実質的にはget_permalink()を呼ぶだけ
• すべての投稿タイプに対応
• $leavenameや$sampleでURLの特殊形式も取得可能
• 新規開発ではget_permalink()を使用推奨

ポイント

• 過去のテーマで使われているのを見ても驚かない
• 新規テーマやプラグインではget_permalink()をベースにする
• URLを埋め込むときは必ずesc_url()を使用