wp_maybe_decline_date() │ WP 4.4.0

Declines or modifies the month in the provided date string. For example for Russian: 15 Май > 15 мая.

Works only for languages where months in the date are declined. Whether the month in the date is declined or not is determined by the following translation line:

'on' === _x( 'off', 'decline months names: on or off' )

The function checks the provided date and if it is in the format: int word ... (15 Май, 15 май 2019 год), then the date will be processed, and the name of the month will be replaced with the name in the genitive case. Thus, for example, 15 Май 2019 will turn into 15 мая 2019.

The function does nothing (returns the provided date) if the months in the language are not declined.

By default in WP the function is hooked to date_i18n:

add_filter( 'date_i18n', 'wp_maybe_decline_date' );

The function accesses the global variable $wp_locale, which contains an object of the class WP_Locale, which has properties: month and month_genitive. It performs transformations based on these properties (case insensitive):

[month] => Array (
	[01] => Январь
	[02] => Февраль
	[03] => Март
	[04] => Апрель
	[05] => Май
	[06] => Июнь
	[07] => Июль
	[08] => Август
	[09] => Сентябрь
	[10] => Октябрь
	[11] => Ноябрь
	[12] => Декабрь
)

[month_genitive] => Array (
	[01] => января
	[02] => февраля
	[03] => марта
	[04] => апреля
	[05] => мая
	[06] => июня
	[07] => июля
	[08] => августа
	[09] => сентября
	[10] => октября
	[11] => ноября
	[12] => декабря
)
Uses: WP_Locale()
1 time — 0.000227 sec (fast) | 50000 times — 0.51 sec (very fast) | PHP 7.2.16, WP 5.2

No Hooks.

Returns

String. The modified date if the site's language implies declension of the date and the provided date (unchanged) otherwise.

Usage

wp_maybe_decline_date( $date );
$date(string) (required)
Formatted time.

Examples

0

#1 Date conversion examples

This will work only if site language date parts can be declined. This option is set in translation string 'on' === _x( 'off', 'decline months names: on or off' ).

For example, suppose our site is running in the Russian language, where months could be declined, then:

echo wp_maybe_decline_date( '15 Май 2019' ); //> 15 мая 2019

The date has the right format, but the month is already written in it correctly - the function does not change anything, although it does all the same operations to find a replacement.

echo wp_maybe_decline_date( '15 Мая 2019' ); //> 15 Мая 2019
echo wp_maybe_decline_date( '15 мая 2019' ); //> 15 мая 2019

The date has the wrong format, the function just returns it without any attempt to change anything.

echo wp_maybe_decline_date( 'Май 2019 года' ); //> Май 2019 года

Notes

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

Changelog

Since 4.4.0 Introduced.
Since 5.4.0 The $format parameter was added.

wp_maybe_decline_date() code WP 7.0

wp-includes/functions.php 
function wp_maybe_decline_date( $date, $format = '' ) {
	global $wp_locale;

	// i18n functions are not available in SHORTINIT mode.
	if ( ! function_exists( '_x' ) ) {
		return $date;
	}

	/*
	 * translators: If months in your language require a genitive case,
	 * translate this to 'on'. Do not translate into your own language.
	 */
	if ( 'on' === _x( 'off', 'decline months names: on or off' ) ) {

		$months          = $wp_locale->month;
		$months_genitive = $wp_locale->month_genitive;

		/*
		 * Match a format like 'j F Y' or 'j. F' (day of the month, followed by month name)
		 * and decline the month.
		 */
		if ( $format ) {
			$decline = preg_match( '#[dj]\.? F#', $format );
		} else {
			// If the format is not passed, try to guess it from the date string.
			$decline = preg_match( '#\b\d{1,2}\.? [^\d ]+\b#u', $date );
		}

		if ( $decline ) {
			foreach ( $months as $key => $month ) {
				$months[ $key ] = '# ' . preg_quote( $month, '#' ) . '\b#u';
			}

			foreach ( $months_genitive as $key => $month ) {
				$months_genitive[ $key ] = ' ' . $month;
			}

			$date = preg_replace( $months, $months_genitive, $date );
		}

		/*
		 * Match a format like 'F jS' or 'F j' (month name, followed by day with an optional ordinal suffix)
		 * and change it to declined 'j F'.
		 */
		if ( $format ) {
			$decline = preg_match( '#F [dj]#', $format );
		} else {
			// If the format is not passed, try to guess it from the date string.
			$decline = preg_match( '#\b[^\d ]+ \d{1,2}(st|nd|rd|th)?\b#u', trim( $date ) );
		}

		if ( $decline ) {
			foreach ( $months as $key => $month ) {
				$months[ $key ] = '#\b' . preg_quote( $month, '#' ) . ' (\d{1,2})(st|nd|rd|th)?([-–]\d{1,2})?(st|nd|rd|th)?\b#u';
			}

			foreach ( $months_genitive as $key => $month ) {
				$months_genitive[ $key ] = '$1$3 ' . $month;
			}

			$date = preg_replace( $months, $months_genitive, $date );
		}
	}

	// Used for locale-specific rules.
	$locale = get_locale();

	if ( 'ca' === $locale ) {
		// " de abril| de agost| de octubre..." -> " d'abril| d'agost| d'octubre..."
		$date = preg_replace( '# de ([ao])#i', " d'\\1", $date );
	}

	return $date;
}

date time