云策 WordPress 开发者社区

函数文档

get_page_by_title()

查看官方原文 ↗
💡 云策文档标注

概述

get_page_by_title() 是一个已弃用的 WordPress 函数，用于根据标题检索页面或自定义文章类型。它直接查询数据库，返回匹配标题的最小 ID 或最早发布日期的文章。开发者应使用 WP_Query 或 get_posts() 作为替代方案。

关键要点

  • 函数已弃用：自 WordPress 6.2.0 起，推荐使用 WP_Query 或 get_posts() 进行查询。
  • 参数说明：接受 $page_title（标题，必需）、$output（返回类型，可选，默认为 OBJECT）和 $post_type（文章类型，可选，默认为 'page'）。
  • 返回类型：成功时返回 WP_Post 对象或数组，失败时返回 null。
  • 匹配行为：如果多个文章标题相同，返回最小 ID 或最早发布日期的文章；使用 MySQL '=' 比较，默认不区分大小写。
  • 注意事项：函数不筛选 post_status，可能返回草稿或垃圾箱中的文章，需自行处理状态过滤。

代码示例

// 替代方案：使用 get_posts()
$posts = get_posts(
    array(
        'post_type'              => 'page',
        'title'                  => 'Sample Page',
        'post_status'            => 'all',
        'numberposts'            => 1,
        'update_post_term_cache' => false,
        'update_post_meta_cache' => false,
        'orderby'                => 'post_date ID',
        'order'                  => 'ASC',
    )
);

$page_got_by_title = null;
if ( ! empty( $posts ) ) {
    $page_got_by_title = $posts[0];
}

// 原函数用法示例（已弃用）
$page = get_page_by_title( 'Sample Page', OBJECT, 'page' );

注意事项

  • 由于函数已弃用，新代码中应避免使用，改用 WP_Query 或 get_posts() 以确保兼容性。
  • 查询时需注意 post_status 过滤，避免返回不需要的文章状态（如草稿、垃圾箱）。
📄 原文内容

Retrieves a page given its title.

Description

If more than one post uses the same title, the post with the smallest ID will be returned.
Be careful: in case of more than one post having the same title, it will check the oldest publication date, not the smallest ID.

Because this function uses the MySQL ‘=’ comparison, $page_title will usually be matched as case-insensitive with default collation.

Parameters

$page_titlestringrequired
Page title.
$outputstringoptional
The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a WP_Post object, an associative array, or a numeric array, respectively.

Default:OBJECT

$post_typestring|arrayoptional
Post type or array of post types. Default 'page'.

Return

WP_Post|array|null WP_Post (or array) on success, or null on failure.

Source

function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' ) {
	_deprecated_function( __FUNCTION__, '6.2.0', 'WP_Query' );
	global $wpdb;

	if ( is_array( $post_type ) ) {
		$post_type           = esc_sql( $post_type );
		$post_type_in_string = "'" . implode( "','", $post_type ) . "'";
		$sql                 = $wpdb->prepare(
			"SELECT ID
			FROM $wpdb->posts
			WHERE post_title = %s
			AND post_type IN ($post_type_in_string)",
			$page_title
		);
	} else {
		$sql = $wpdb->prepare(
			"SELECT ID
			FROM $wpdb->posts
			WHERE post_title = %s
			AND post_type = %s",
			$page_title,
			$post_type
		);
	}

	$page = $wpdb->get_var( $sql );

	if ( $page ) {
		return get_post( $page, $output );
	}

	return null;
}

View all references View on Trac View on GitHub

Uses Description
esc_sql()wp-includes/formatting.php

Escapes data for use in a MySQL query.
_deprecated_function()wp-includes/functions.php

Marks a function as deprecated and inform when it has been used.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.
wpdb::get_var()wp-includes/class-wpdb.php

Retrieves one value from the database.
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.

Show 3 moreShow less

Changelog

Version Description
6.2.0 Deprecated. Use WP_Query.
3.0.0 The $post_type parameter was added.
2.1.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content


    Gabor Lippert


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Deprecated !!!

    Here’s the link to the deprecation info article: https://make.wordpress.org/core/2023/03/06/get_page_by_title-deprecated/

    In a nutshell:

    Peter Wilson recommends the following alternative:

    $posts = get_posts(
    array(
        'post_type'              => 'page',
        'title'                  => 'Sample Page',
        'post_status'            => 'all',
        'numberposts'            => 1,
        'update_post_term_cache' => false,
        'update_post_meta_cache' => false,           
        'orderby'                => 'post_date ID',
        'order'                  => 'ASC',
    )
);

$page_got_by_title = null;
 
if ( ! empty( $posts ) ) {
    $page_got_by_title = $posts[0];
}

    Or, alternatively, you can use the new WP_Query() method as well.

  2. Skip to note 7 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    How To Find WordPress Page ID By Title Then Replace the_content()

    In this example, we find the page id of “Sample Page” then replace the page’s the_content() with “Hello World!”

    function my_content($content) {
	$page = get_page_by_title( 'Sample Page' );
	if ( is_page($page->ID) )
		$content = "Hello World!";
	return $content;
}
add_filter('the_content', 'my_content');

  3. Skip to note 8 content


    Akira Tachibana


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    How to Find WordPress Custom Post Type by Title

    This is useful for Custom Post Types. Below, we find the $post array of a Custom Post Type “link” with a title of “World Peace Now”:

    $mypost = get_page_by_title('World Peace Now', OBJECT, 'link');
print_r($mypost);

    This comment was copied from Codex.