date_i18n( string $format, int|bool $timestamp_with_offset = false, bool $gmt = false ): string
- Since
- 0.71, 5.3.0
- Source
wp-includes/functions.php:179
Description
If the locale specifies the locale month and weekday, then the locale will take over the format for the date. If it isn't, then the date format string will be used instead.
Note that due to the way WP typically generates a sum of timestamp and offset with strtotime(), it implies offset added at a current time, not at the time the timestamp represents. Storing such timestamps or calculating them differently will lead to invalid output.
Compatibility
- WordPress
- since 5.3.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$formatstring- Format to display the date.
$timestamp_with_offsetint|booloptional- A sum of Unix timestamp and timezone offset in seconds. Default false.Default:
false $gmtbooloptional- Whether to use GMT timezone. Only applies if timestamp is not provided. Default false.Default:
false
Return value
string- The date, translated if locale specifies it.
Performance profile
How much work a call to date_i18n() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Moderate
- Scaling
- Constant
- Instructions
- 19–48
- Plugin surface
- 1 hook
- Called by
- 22
Reads stored settings via get_option(), cached per request but not free on a cold cache.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 65.
Third-party callbacks on 'date_i18n' run inside this call, and their cost is not bounded by anything here.
22 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly - optionoption read or write
get_option()one call below date_i18n()
Further down the call graph this can also reach cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 6 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost date_i18n() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
$timestamp && $format === "U" | 19 | apply_filters() |
!$timestamp && $format === "U" | 24 | current_time(), apply_filters() |
$timestamp && $format !== "U" && $timestamp_with_offset === false | 25–30 | wp_date(), apply_filters() |
!$timestamp && $format !== "U" && $timestamp_with_offset === false | 30–35 | current_time(), wp_date(), apply_filters() |
$timestamp && $format !== "U" && $timestamp_with_offset !== false | 41–43 | gmdate(), wp_timezone(), date_create(), ->getTimestamp(), wp_date(), apply_filters() |
!$timestamp && $format !== "U" && $timestamp_with_offset !== false | 46–48 | current_time(), gmdate(), wp_timezone(), date_create(), ->getTimestamp(), wp_date(), apply_filters() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 65 | 19–48 | 5 | |
| 8.5 | 65 | 19–48 | 5 | |
| 8.4 | 65 | 19–48 | 5 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 67 | 21–50 | 5 | |
| 8.2 | 67 | 21–50 | 5 | |
| 8.1 | 67 | 21–50 | 5 | |
| 7.4 | 67 | 21–50 | 5 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while date_i18n() runs, in this order:
- apply_filters( date_i18n )filterline 220 (+41 into the body)
Filters the date formatted based on the locale.
Uses · 5
- current_time()Retrieves the current time based on specified type.
- wp_date()Retrieves the date, in localized format.
- wp_timezone()Retrieves the timezone of the site as a `DateTimeZone` object.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- DateTimeZone::__construct()
Used by · 22
- WP_Application_Passwords_List_Table::column_created()Handles the created column output.
- WP_Application_Passwords_List_Table::column_last_used()Handles the last used column output.
- WP_Community_Events::format_event_data_time()Adds formatted date and time items for each event in an API response.
- WP_Privacy_Policy_Content::privacy_policy_guide()Outputs the privacy policy guide together with content from the theme and plugins.
- WP_Privacy_Requests_Table::get_timestamp_as_date()Converts a timestamp for display.
- attachment_submit_meta_box()Displays attachment submit form fields.
- block_core_breadcrumbs_get_archive_breadcrumbs()Generates breadcrumb items for archive pages.
- heartbeat_autosave()Performs autosave with heartbeat.
- post_submit_meta_box()Displays post submit form fields.
- render_block_core_latest_comments()Renders the `core/latest-comments` block on server.
- render_block_core_rss()Renders the `core/rss` block on server.
- wp_ajax_date_format()Handles formatting a date via AJAX.
Show all 22
- wp_ajax_time_format()Handles formatting a time via AJAX.
- wp_ajax_wp_fullscreen_save_post()Handles saving posts from the fullscreen editor via AJAX.
- wp_dashboard_recent_posts()Generates Publishing Soon and Recently Published sections.
- wp_get_archives()Displays archive links based on type and format.
- wp_post_revision_title()Retrieves formatted date timestamp of a revision (linked to that revisions's page).
- wp_post_revision_title_expanded()Retrieves formatted date timestamp of a revision (linked to that revisions's page).
- wp_prepare_revisions_for_js()Prepare revisions for JavaScript.
- wp_privacy_send_personal_data_export_email()Send an email to the user with a link to the personal data export file
- wp_user_personal_data_exporter()Finds and exports personal data associated with an email address from the user and user_meta table.
- wp_widget_rss_output()Displays the RSS entries in a list.
Source code
function date_i18n( $format, $timestamp_with_offset = false, $gmt = false ) { $timestamp = $timestamp_with_offset; // If timestamp is omitted it should be current time (summed with offset, unless `$gmt` is true). if ( ! is_numeric( $timestamp ) ) { // phpcs:ignore WordPress.DateTime.CurrentTimeTimestamp.Requested $timestamp = current_time( 'timestamp', $gmt ); } /* * This is a legacy implementation quirk that the returned timestamp is also with offset. * Ideally this function should never be used to produce a timestamp. */ if ( 'U' === $format ) { $date = $timestamp; } elseif ( $gmt && false === $timestamp_with_offset ) { // Current time in UTC. $date = wp_date( $format, null, new DateTimeZone( 'UTC' ) ); } elseif ( false === $timestamp_with_offset ) { // Current time in site's timezone. $date = wp_date( $format ); } else { /* * Timestamp with offset is typically produced by a UTC `strtotime()` call on an input without timezone. * This is the best attempt to reverse that operation into a local time to use. */ $local_time = gmdate( 'Y-m-d H:i:s', $timestamp ); $timezone = wp_timezone(); $datetime = date_create( $local_time, $timezone ); $date = wp_date( $format, $datetime->getTimestamp(), $timezone ); } /** * Filters the date formatted based on the locale. * * @since 2.8.0 * * @param string $date Formatted date string. * @param string $format Format to display the date. * @param int $timestamp A sum of Unix timestamp and timezone offset in seconds. * Might be without offset if input omitted timestamp but requested GMT. * @param bool $gmt Whether to use GMT timezone. Only applies if timestamp was not provided. */ $date = apply_filters( 'date_i18n', $date, $format, $timestamp, $gmt ); return $date;}Changelog
Introduced in 0.71. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.