云策 WordPress 开发者社区

函数文档

get_blog_details()

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

概述

get_blog_details() 函数用于从 WordPress 多站点网络的 blogs 表和博客选项中检索指定博客的详细信息。它支持通过多种方式指定博客，并返回 WP_Site 对象或 false。

关键要点

  • 函数参数：$fields 可以是博客 ID、博客 slug 或数组（包含 blog_id、domain、path 等字段），默认使用当前博客 ID；$get_all 控制是否获取所有详情（包括博客选项），默认为 true。
  • 返回值：成功时返回 WP_Site 对象，包含博客核心属性（如 blogname、siteurl、post_count、home），失败时返回 false。
  • 缓存机制：函数利用 wp_cache_get 和 wp_cache_set 进行缓存优化，减少数据库查询。
  • 多站点支持：处理子域名安装和路径配置，自动切换博客上下文以获取选项。
  • 弃用状态：自 WordPress 4.7.0 起，推荐使用 get_site() 替代，blog_details 过滤器已弃用。

代码示例

// 获取当前博客详情
$details = get_blog_details();

// 通过博客 ID 获取详情
$details = get_blog_details( 2 );

// 通过博客 slug 获取详情
$details = get_blog_details( 'example' );

// 仅获取 blogs 表详情，不包含选项
$details = get_blog_details( null, false );

// 使用数组参数指定 domain 和 path
$details = get_blog_details( array( 'domain' => 'example.com', 'path' => '/' ) );

注意事项

  • 函数默认返回的博客详情有限，仅包括 blogname、siteurl、post_count 和 home；如需其他选项，应使用 get_blog_option()。
  • 在 WordPress 4.7.0 及以上版本，建议优先使用 get_site() 函数，以遵循最新的 API 标准。
  • 函数内部涉及缓存操作，开发时需注意缓存一致性，避免数据过时。
📄 原文内容

Retrieves the details for a blog from the blogs table and blog options.

Parameters

$fieldsint|string|arrayoptional
A blog ID, a blog slug, or an array of fields to query against.
Defaults to the current blog ID.

Default:null

$get_allbooloptional
Whether to retrieve all details or only the details in the blogs table.
Default is true.

Default:true

Return

WP_Site|false Blog details on success. False on failure.

Source

function get_blog_details( $fields = null, $get_all = true ) {
	global $wpdb;

	if ( is_array( $fields ) ) {
		if ( isset( $fields['blog_id'] ) ) {
			$blog_id = $fields['blog_id'];
		} elseif ( isset( $fields['domain'] ) && isset( $fields['path'] ) ) {
			$key  = md5( $fields['domain'] . $fields['path'] );
			$blog = wp_cache_get( $key, 'blog-lookup' );
			if ( false !== $blog ) {
				return $blog;
			}
			if ( str_starts_with( $fields['domain'], 'www.' ) ) {
				$nowww = substr( $fields['domain'], 4 );
				$blog  = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->blogs WHERE domain IN (%s,%s) AND path = %s ORDER BY CHAR_LENGTH(domain) DESC", $nowww, $fields['domain'], $fields['path'] ) );
			} else {
				$blog = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->blogs WHERE domain = %s AND path = %s", $fields['domain'], $fields['path'] ) );
			}
			if ( $blog ) {
				wp_cache_set( $blog->blog_id . 'short', $blog, 'blog-details' );
				$blog_id = $blog->blog_id;
			} else {
				return false;
			}
		} elseif ( isset( $fields['domain'] ) && is_subdomain_install() ) {
			$key  = md5( $fields['domain'] );
			$blog = wp_cache_get( $key, 'blog-lookup' );
			if ( false !== $blog ) {
				return $blog;
			}
			if ( str_starts_with( $fields['domain'], 'www.' ) ) {
				$nowww = substr( $fields['domain'], 4 );
				$blog  = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->blogs WHERE domain IN (%s,%s) ORDER BY CHAR_LENGTH(domain) DESC", $nowww, $fields['domain'] ) );
			} else {
				$blog = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->blogs WHERE domain = %s", $fields['domain'] ) );
			}
			if ( $blog ) {
				wp_cache_set( $blog->blog_id . 'short', $blog, 'blog-details' );
				$blog_id = $blog->blog_id;
			} else {
				return false;
			}
		} else {
			return false;
		}
	} else {
		if ( ! $fields ) {
			$blog_id = get_current_blog_id();
		} elseif ( ! is_numeric( $fields ) ) {
			$blog_id = get_id_from_blogname( $fields );
		} else {
			$blog_id = $fields;
		}
	}

	$blog_id = (int) $blog_id;

	$all     = $get_all ? '' : 'short';
	$details = wp_cache_get( $blog_id . $all, 'blog-details' );

	if ( $details ) {
		if ( ! is_object( $details ) ) {
			if ( -1 === $details ) {
				return false;
			} else {
				// Clear old pre-serialized objects. Cache clients do better with that.
				wp_cache_delete( $blog_id . $all, 'blog-details' );
				unset( $details );
			}
		} else {
			return $details;
		}
	}

	// Try the other cache.
	if ( $get_all ) {
		$details = wp_cache_get( $blog_id . 'short', 'blog-details' );
	} else {
		$details = wp_cache_get( $blog_id, 'blog-details' );
		// If short was requested and full cache is set, we can return.
		if ( $details ) {
			if ( ! is_object( $details ) ) {
				if ( -1 === $details ) {
					return false;
				} else {
					// Clear old pre-serialized objects. Cache clients do better with that.
					wp_cache_delete( $blog_id, 'blog-details' );
					unset( $details );
				}
			} else {
				return $details;
			}
		}
	}

	if ( empty( $details ) ) {
		$details = WP_Site::get_instance( $blog_id );
		if ( ! $details ) {
			// Set the full cache.
			wp_cache_set( $blog_id, -1, 'blog-details' );
			return false;
		}
	}

	if ( ! $details instanceof WP_Site ) {
		$details = new WP_Site( $details );
	}

	if ( ! $get_all ) {
		wp_cache_set( $blog_id . $all, $details, 'blog-details' );
		return $details;
	}

	$switched_blog = false;

	if ( get_current_blog_id() !== $blog_id ) {
		switch_to_blog( $blog_id );
		$switched_blog = true;
	}

	$details->blogname   = get_option( 'blogname' );
	$details->siteurl    = get_option( 'siteurl' );
	$details->post_count = get_option( 'post_count' );
	$details->home       = get_option( 'home' );

	if ( $switched_blog ) {
		restore_current_blog();
	}

	/**
	 * Filters a blog's details.
	 *
	 * @since MU (3.0.0)
	 * @deprecated 4.7.0 Use 'site_details' instead.
	 *
	 * @param WP_Site $details The blog details.
	 */
	$details = apply_filters_deprecated( 'blog_details', array( $details ), '4.7.0', 'site_details' );

	wp_cache_set( $blog_id . $all, $details, 'blog-details' );

	$key = md5( $details->domain . $details->path );
	wp_cache_set( $key, $details, 'blog-lookup' );

	return $details;
}

View all references View on Trac View on GitHub

Hooks

apply_filters_deprecated( ‘blog_details’, WP_Site $details )

Filters a blog’s details.

Uses Description
apply_filters_deprecated()wp-includes/plugin.php

Fires functions attached to a deprecated filter hook.
WP_Site::get_instance()wp-includes/class-wp-site.php

Retrieves a site from the database by its ID.
WP_Site::__construct()wp-includes/class-wp-site.php

Creates a new WP_Site object.
wp_cache_set()wp-includes/cache.php

Saves the data to the cache.
wp_cache_delete()wp-includes/cache.php

Removes the cache contents matching key and group.
is_subdomain_install()wp-includes/ms-load.php

Whether a subdomain configuration is enabled.
switch_to_blog()wp-includes/ms-blogs.php

Switches the current blog.
restore_current_blog()wp-includes/ms-blogs.php

Restores the current blog, after calling switch_to_blog() .
get_id_from_blogname()wp-includes/ms-blogs.php

Retrieves a site’s ID given its (subdomain or directory) slug.
wpdb::get_row()wp-includes/class-wpdb.php

Retrieves one row from the database.
wp_cache_get()wp-includes/cache.php

Retrieves the cache contents from the cache by key and group.
get_current_blog_id()wp-includes/load.php

Retrieves the current site ID.
get_option()wp-includes/option.php

Retrieves an option value based on an option name.
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.

Show 9 moreShow less

Changelog

Version Description
MU (3.0.0) Introduced.

User Contributed Notes

  1. Skip to note 3 content


    西門 正 Code Guy


    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

    Since there is practical needs about getting additional information from multisite like this post, it might worth to note here of what get_blog_details() is returning. It could save people, who is not familiar with WordPress, the time from trying.

    By default, the get_blog_details() only returns the following details of the site.

    • blogname
    • siteurl
    • post_count
    • home

    If in case, need to get other information such as blog description of one of the sites. May achieve by using

    get_blog_option( $blog_id, 'blogdescription' );

    Reference: get_blog_option()