wp_date() │ WP 5.3.0

Gets the localized date (translated into the current language) from the given Unix timestamp.

This function is a wrapper for the PHP function date().

If the output date uses a format with the month or week as a string, the function will attempt to translate them into the current language. In other cases, it is analogous to date() in PHP.

This is a new function intended to replace date_i18n().

Note that this function returns the date, not outputs it to the screen.

This function, unlike date_i18n(), requires a Unix timestamp to be passed without adding the site's timezone offset.

The timezone offset is added automatically within the function based on the third parameter $timezone, where an arbitrary timezone offset can be specified.

In connection with the introduction of a new API for working with time in version 5.3:

Not recommended:

Recommended:

Below are the DATE_RFC3339 formats.

Also read: Date/Time in WordPress.

Uses: WP_Locale(), wp_timezone()
Used By: date_i18n(), mysql2date()
Hooks from the function

Returns

String|false. The translated date. False when an incorrect timestamp is provided.

Usage

wp_date( $format, $timestamp, $timezone );
$format(string) (required)
The format in which to output the date, example: F j, Y - November 6, 2010. Full list of formats. The format can use the option get_option( 'date_format' ), which is set in the "Settings" section.
$timestamp(number)
The Unix timestamp from which the date will be obtained in the specified format. By default, the current timestamp time() is used.
Default: null - (time() - current UNIX time)
$timezone(DateTimeZone)
The timezone that will be applied to the specified timestamp. Default: wp_timezone().
Default: null (current timezone from site options)

Examples

0

#1 Localization of the php function date() in WordPress

Current time:

$format = 'j F Y H:i:s';

echo wp_date( $format );   // March 24, 2021 08:12:07 (website time = +5 hours)
echo date_i18n( $format ); // March 24, 2021 08:12:07 (website time = +5 hours)
echo date( $format );      // March 24, 2021 03:12:07 (UTC time)

Specified time:

echo wp_date( 'j F Y H:i:s', 0 );
// January 1, 1970 06:00:00

echo wp_date( 'j M Y H:i:s', strtotime('1999-11-15') );
// 15 Nov 1999 05:00:00 (site time = +5 hours)

echo wp_date( 'j M Y H:i:s', strtotime('1999-11-15'), new DateTimeZone('UTC') );
// 15 Nov 1999 00:00:00 (UTC time)
0

#2 Get a translatable the_date() equivalent

To do this you will need:

echo wp_date( get_option( 'date_format' ), get_post_timestamp() );

Useful information: https://make.wordpress.org/core/2019/09/23/date-time-improvements-wp-5-3/

Notes

  • Global. WP_Locale. $wp_locale WordPress date and time locale object.

Changelog

Since 5.3.0 Introduced.

wp_date() code WP 6.8.3

wp-includes/functions.php 
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;
}

date time