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
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. |
Skip to note 6 content
Cameron Jones
Useful background information: https://make.wordpress.org/core/2019/09/23/date-time-improvements-wp-5-3/
Skip to note 7 content
Luiz Bills
PHP Date Formats: https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters
Skip to note 8 content
Marc Heatley
To get a translatable
the_date();equivalent, you will need:echo wp_date( get_option( 'date_format' ), get_post_timestamp() ); ?>Skip to note 9 content
Rahi Saiful
To get the date and time from the timestamp you can use this code
$dateTimeFormat = get_option( 'date_format' ) . ' ' . get_option( 'time_format' ); echo wp_date( $dateTimeFormat, get_post_timestamp() );You can use your own timestamp instead of get_post_timestamp()
Skip to note 10 content
Marc Heatley
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 echoget_wp_date();would just returnI think the reason is becase it’s a drop-in replacement for PHP’s
date();not WordPress’the_date();