函数文档

wp_date()

💡 云策文档标注

概述

wp_date() 是 WordPress 5.3 引入的新函数,用于以本地化格式检索日期,旨在替代 date_i18n() 并避免其遗留问题。它接受 Unix 时间戳和时区参数,返回本地化日期字符串或 false。

关键要点

  • wp_date() 是 date_i18n() 的现代替代品,处理时间戳时无需与时区偏移相加。
  • 参数包括:$format(必需,PHP 日期格式)、$timestamp(可选,Unix 时间戳,默认为当前时间)、$timezone(可选,DateTimeZone 对象,默认为站点时区)。
  • 返回本地化日期字符串,若时间戳无效则返回 false。
  • 内部使用 WP_Locale 处理月份、星期等本地化,并支持 wp_date 过滤器进行自定义。
  • 相关函数包括 wp_timezone()、wp_maybe_decline_date() 和 WP_Locale 类方法。

代码示例

// 获取当前日期,使用站点日期格式
echo wp_date( get_option( 'date_format' ), get_post_timestamp() );

// 获取自定义时间戳的日期和时间
$dateTimeFormat = get_option( 'date_format' ) . ' ' . get_option( 'time_format' );
echo wp_date( $dateTimeFormat, $timestamp );

注意事项

  • wp_date() 仅返回日期字符串,不直接输出,需使用 echo 显示。
  • 与 date_i18n() 不同,它接受纯 Unix 时间戳,而非时间戳与时区偏移之和。
  • 确保时间戳为有效数值,否则函数返回 false。

📄 原文内容

Retrieves the date, in localized format.

Description

This is a newer function, intended to replace date_i18n() without legacy quirks in it.

Note that, unlike date_i18n(), this function accepts a true Unix timestamp, not summed with timezone offset.

Parameters

$formatstringrequired
PHP date format.
$timestampint|nulloptional
Unix timestamp. Defaults to current time.

Default:null

$timezoneDateTimeZone|nulloptional
Timezone to output result in. Defaults to timezone from site settings.

Default:null

Return

string|false The date, translated if locale specifies it. False on invalid timestamp input.

Source

function wp_date( $format, $timestamp = null, $timezone = null ) {
	global $wp_locale;

	if ( null === $timestamp ) {
		$timestamp = time();
	} elseif ( ! is_numeric( $timestamp ) ) {
		return false;
	}

	if ( ! $timezone ) {
		$timezone = wp_timezone();
	}

	$datetime = date_create( '@' . $timestamp );
	$datetime->setTimezone( $timezone );

	if ( empty( $wp_locale->month ) || empty( $wp_locale->weekday ) ) {
		$date = $datetime->format( $format );
	} else {
		// We need to unpack shorthand `r` format because it has parts that might be localized.
		$format = preg_replace( '/(?<!--\\)r/', DATE_RFC2822, $format );

		$new_format    = '';
		$format_length = strlen( $format );
		$month         = $wp_locale--->get_month( $datetime->format( 'm' ) );
		$weekday       = $wp_locale->get_weekday( $datetime->format( 'w' ) );

		for ( $i = 0; $i < $format_length; $i++ ) {
			switch ( $format[ $i ] ) {
				case 'D':
					$new_format .= addcslashes( $wp_locale->get_weekday_abbrev( $weekday ), '\A..Za..z' );
					break;
				case 'F':
					$new_format .= addcslashes( $month, '\A..Za..z' );
					break;
				case 'l':
					$new_format .= addcslashes( $weekday, '\A..Za..z' );
					break;
				case 'M':
					$new_format .= addcslashes( $wp_locale->get_month_abbrev( $month ), '\A..Za..z' );
					break;
				case 'a':
					$new_format .= addcslashes( $wp_locale->get_meridiem( $datetime->format( 'a' ) ), '\A..Za..z' );
					break;
				case 'A':
					$new_format .= addcslashes( $wp_locale->get_meridiem( $datetime->format( 'A' ) ), '\A..Za..z' );
					break;
				case '\':
					$new_format .= $format[ $i ];

					// If character follows a slash, we add it without translating.
					if ( $i < $format_length ) {
						$new_format .= $format[ ++$i ];
					}
					break;
				default:
					$new_format .= $format[ $i ];
					break;
			}
		}

		$date = $datetime->format( $new_format );
		$date = wp_maybe_decline_date( $date, $format );
	}

	/**
	 * Filters the date formatted based on the locale.
	 *
	 * @since 5.3.0
	 *
	 * @param string       $date      Formatted date string.
	 * @param string       $format    Format to display the date.
	 * @param int          $timestamp Unix timestamp.
	 * @param DateTimeZone $timezone  Timezone.
	 */
	$date = apply_filters( 'wp_date', $date, $format, $timestamp, $timezone );

	return $date;
}

Hooks

apply_filters( ‘wp_date’, string $date, string $format, int $timestamp, DateTimeZone $timezone )

Filters the date formatted based on the locale.

Changelog

Version Description
5.3.0 Introduced.

User Contributed Notes

  1. Skip to note 10 content

    Be aware that this function returns a date, but not echoes it.

    When I picked it up my muscle memory told me

    • wp_date(); would echo
    • and something like get_wp_date(); would just return

    I think the reason is becase it’s a drop-in replacement for PHP’s date(); not WordPress’ the_date();