get_sample_permalink()
云策文档标注
概述
get_sample_permalink() 函数基于文章名称返回一个示例固定链接，主要用于生成包含占位符的链接和文章名称。它处理文章状态、名称覆盖和层级结构，并支持过滤器自定义。
关键要点
- 函数返回一个数组，包含带占位符的示例固定链接和文章名称。
- 参数包括 $post（必需，文章ID或对象）、$title（可选，覆盖标题）和 $name（可选，覆盖文章名称）。
- 自动处理草稿等状态，将其视为已发布以生成链接。
- 支持层级文章类型（如页面），通过 get_page_uri() 处理路径。
- 使用 wp_unique_post_slug() 确保文章名称唯一性。
- 提供 apply_filters('get_sample_permalink') 过滤器，允许自定义返回结果。
代码示例
// 获取文章ID为123的示例固定链接
$sample = get_sample_permalink(123);
echo $sample[0]; // 输出带占位符的链接
echo $sample[1]; // 输出文章名称注意事项
- 函数内部会临时修改文章状态和名称，但最终会恢复原值，不影响实际数据。
- 对于层级文章类型，占位符 %pagename% 可能包含父级路径。
- 如果 $name 参数为空，会使用 $title 生成文章名称。
原文内容
Returns a sample permalink based on the post name.
Parameters
$postint|WP_Postrequired-
Post ID or post object.
$titlestring|nulloptional-
Title to override the post’s current title when generating the post name.
Default:
null $namestring|nulloptional-
Name to override the post name.
Default:
null
Source
function get_sample_permalink( $post, $title = null, $name = null ) {
$post = get_post( $post );
if ( ! $post ) {
return array( '', '' );
}
$ptype = get_post_type_object( $post->post_type );
$original_status = $post->post_status;
$original_date = $post->post_date;
$original_name = $post->post_name;
$original_filter = $post->filter;
// Hack: get_permalink() would return plain permalink for drafts, so we will fake that our post is published.
if ( in_array( $post->post_status, array( 'auto-draft', 'draft', 'pending', 'future' ), true ) ) {
$post->post_status = 'publish';
$post->post_name = sanitize_title( $post->post_name ? $post->post_name : $post->post_title, $post->ID );
}
/*
* If the user wants to set a new name -- override the current one.
* Note: if empty name is supplied -- use the title instead, see #6072.
*/
if ( ! is_null( $name ) ) {
$post->post_name = sanitize_title( $name ? $name : $title, $post->ID );
}
$post->post_name = wp_unique_post_slug( $post->post_name, $post->ID, $post->post_status, $post->post_type, $post->post_parent );
$post->filter = 'sample';
$permalink = get_permalink( $post, true );
// Replace custom post_type token with generic pagename token for ease of use.
$permalink = str_replace( "%$post->post_type%", '%pagename%', $permalink );
// Handle page hierarchy.
if ( $ptype->hierarchical ) {
$uri = get_page_uri( $post );
if ( $uri ) {
$uri = untrailingslashit( $uri );
$uri = strrev( stristr( strrev( $uri ), '/' ) );
$uri = untrailingslashit( $uri );
}
/** This filter is documented in wp-admin/edit-tag-form.php */
$uri = apply_filters( 'editable_slug', $uri, $post );
if ( ! empty( $uri ) ) {
$uri .= '/';
}
$permalink = str_replace( '%pagename%', "{$uri}%pagename%", $permalink );
}
/** This filter is documented in wp-admin/edit-tag-form.php */
$permalink = array( $permalink, apply_filters( 'editable_slug', $post->post_name, $post ) );
$post->post_status = $original_status;
$post->post_date = $original_date;
$post->post_name = $original_name;
$post->filter = $original_filter;
/**
* Filters the sample permalink.
*
* @since 4.4.0
*
* @param array $permalink {
* Array containing the sample permalink with placeholder for the post name, and the post name.
*
* @type string $0 The permalink with placeholder for the post name.
* @type string $1 The post name.
* }
* @param int $post_id Post ID.
* @param string $title Post title.
* @param string $name Post name (slug).
* @param WP_Post $post Post object.
*/
return apply_filters( 'get_sample_permalink', $permalink, $post->ID, $title, $name, $post );
}
Hooks
- apply_filters( ‘editable_slug’, string $slug, WP_Term|WP_Post $tag )
-
Filters the editable slug for a post or term.
- apply_filters( ‘get_sample_permalink’, array $permalink, int $post_id, string $title, string $name, WP_Post $post )
-
Filters the sample permalink.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |