ドキュメント

2026.07.15

開発者向けに、Default Permalink のフック・オプション・カスタマイズ方法をまとめています。

スラッグ置換の仕組み

wp_unique_post_slug フィルター（優先度 10、引数 5 個）にフックし、以下の条件をすべて満たす場合のみスラッグを置換します。

  1. オプション df_enable の値が "Enable" である（設定画面で有効化済み）
  2. 投稿タイプが置換対象である（オプション未保存の場合は全公開投稿タイプが対象）
  3. スラッグが正規表現 /(%[0-9a-f]{2})+/ にマッチする（URL エンコードされたマルチバイト文字を含む）
  4. ユーザーがスラッグを明示指定していない（保存時の入力に post_name がない。wp_insert_post_empty_content フィルターで保存開始時に記録して判定する）

REST API・WP-CLI・wp_insert_post() の直接呼び出しなど ID 未確定の新規作成では、いったん空のスラッグを返し、wp_insert_post() が挿入後に ID 付きでスラッグを作り直すときに置換します。生成したスラッグは wp_unique_post_slug() で一意化され、重複時は -2 などが付きます。

実際の保存で置換したときは post meta _dp_slug_replaced に新しいスラッグを保存し、通知に使用します（パーマリンクのプレビューでは記録しません）。ブロックエディターでは保存の REST レスポンスに dp_slug_replaced として含めて記録を削除し、エディター内で通知します。クラシックエディターでは次回の編集画面の表示時に通知して削除します。

通知を記録するのは、管理画面（admin-ajax を除く）と REST API からの保存だけです（1.9.2〜）。WP-CLI・インポート（WP_IMPORTING）・cron（DOING_CRON）・クイック編集などの ajax の保存では記録しません（スラッグの置換は行います）。この判定は default_permalink_record_notice フィルター（bool）で変更できます。ブロックエディターでは、記録が投稿の現在のスラッグと一致するときだけ通知します（1.10.2〜。以前の保存の記録が残っていても、スラッグを変えた保存では通知しない）。

「投稿日 + ID」形式（date）は、既存投稿の保存ではこれから保存する投稿日（予約日など。日付未確定の下書きは現在時刻）で生成します（1.10.1〜）。クラシックエディターのパーマリンク編集でユーザーが入力したスラッグは、プレビューでも置換しません。

オプション

オプション名値説明
df_enable"Enable" / ""機能の有効・無効
df_slug_formatpost_type / date / randomスラッグ形式（デフォルト: post_type）
df_post_types投稿タイプ名の配列置換対象の投稿タイプ。未保存（v1.4 より前からのインストール）の場合は全公開投稿タイプが対象
df_taxonomiesタクソノミー名の配列スラッグを置換するタクソノミー（1.7.0〜）。既定は空（対象なし）。post_format は選べない

default_permalink_slug フィルター

生成されたスラッグは default_permalink_slug フィルターを通るため、テーマや他のプラグインから形式を自由にカスタマイズできます。

/**
 * 生成されるスラッグを「item-{投稿ID}」形式に変更する例
 *
 * @param string $slug      生成されたスラッグ。
 * @param int    $post_id   投稿 ID。
 * @param string $post_type 投稿タイプ。
 */
add_filter( 'default_permalink_slug', function ( $slug, $post_id, $post_type ) {
	return 'item-' . $post_id;
}, 10, 3 );

default_permalink_term_slug フィルター

対象のタクソノミーで新しく追加したタームのスラッグ（既定は {taxonomy}-{term_id}。_ は - に置換）は default_permalink_term_slug フィルターを通ります。結果は sanitize_title() と wp_unique_term_slug() で一意化されます。

/**
 * タームのスラッグを「topic-{ターム ID}」形式に変更する例
 *
 * @param string $slug     生成されたスラッグ(例: category-12)。
 * @param int    $term_id  ターム ID。
 * @param string $taxonomy タクソノミー名。
 */
add_filter( 'default_permalink_term_slug', function ( $slug, $term_id, $taxonomy ) {
	return 'topic-' . $term_id;
}, 10, 3 );

default_permalink_record_notice フィルター

スラッグを置換した保存で、通知用の記録（_dp_slug_replaced）を残すかどうかを決めます（1.9.2〜）。引数は既定の判定（管理画面・REST API の保存なら true、WP-CLI・インポート・cron・ajax なら false）です。1.9.1 以前と同じく、どの保存でも記録するには次のようにします。

add_filter( 'default_permalink_record_notice', '__return_true' );

WP-CLI コマンド

  • wp default-permalink status: 有効/無効・スラッグ形式・対象の投稿タイプとタクソノミー・一括変換の対象件数を表示
  • wp default-permalink convert [--dry-run]: 設定画面の一括変換と同じ処理を件数の上限なしで実行。--dry-run は変更せずに対象と新しいスラッグを表で表示。変換できない投稿があっても先に進み、1件でも失敗すると終了コード 1
  • convert のオプション（1.10.0〜）: --post_type=<types>（カンマ区切り。設定の対象外は警告して除外）、--limit=<number>（その件数で止め、残り件数と続きの --after を表示）、--after=<id>（1.10.1〜。その ID より後だけを処理）
  • 一括変換（設定画面・WP-CLI）は投稿の状態と公開予定を変えません。予定時刻を過ぎた予約投稿も予約のままスラッグだけを変換します（1.10.2〜）

サイトヘルス

site_status_tests フィルターで直接テスト default_permalink を追加します（1.10.0〜、WordPress 5.2 以降）。df_enable が "Enable" でなければ recommended（設定画面へのリンク）、有効なら good です。マルチバイトのスラッグの投稿が残っている場合も good のまま、説明に件数と一括変換の案内を添えます（1.10.1〜）。

アンインストール

プラグインを削除すると uninstall.php が実行され、上記のオプションと通知用の post meta _dp_slug_replaced はすべて削除されます。マルチサイトではネットワークのすべてのサイトから削除します（1.9.2〜）。変換済みの投稿スラッグは投稿データそのものなので、そのまま残ります。

ソースコード

ホーム
ドキュメント
タイトルとURLをコピーしました