Some thoughts: the $timezone parameter in the wp_date() function allows developers to specify in which (local) timezone the date should be formatted. There is however not a parameter for the (local) language to format the date in. The language will default to the language from the settings. Is it not more consistent to do the same for the timezone? Or we could end up with other internationalization parameters?

function wp_date( $format, $timestamp = null, $timezone = null, WP_Locale $locale = null ) {}

Would wp_datetime not be a better name to make it more clear that you can format date/time?

If i understand correctly get_post_datetime() will always return a DateTime object with timezone DateTimeZone( 'UTC' )? What if WordPress developers want a DateTime object with a local DateTimeZone from the default settings? The code below could result in errors when on PHP < 5.5 and using an offset timezone.

$datetime = get_post_datetime();
$datetime->setTimezone( wp_timezone() );

Maybe developers should have the following options for the $field parameter?

$d1 = get_post_datetime( null, 'date' ); // timezone from settings
$d2 = get_post_datetime( null, 'date_gmt' ); // UTC timezone
$d3 = get_post_datetime( null, 'modified' ); // timezone from settings
$d4 = get_post_datetime( null, 'modified_gmt' ); // UTC timezone

The language will default to the language from the settings. Is it not more consistent to do the same for the timezone?

This is the intent and what inline doc says. :) $timezone Optional. Timezone to output result in. Defaults to timezone from settings.

Would wp_datetime not be a better name to make it more clear that you can format date/time?

No, upstream function is date(). datetime typically stands for DateTime object or related.

If i understand correctly get_post_datetime() will always return a DateTime object with timezone DateTimeZone( 'UTC' )?

No, the intent is to return object set to local time zone. I'll adjust inline doc. Against having argument for it, if something else is needed then object should be manipulated for it.

This is the intent and what inline doc says. :) $timezone Optional. Timezone to output result in. Defaults to timezone from settings.

I mean: why have a $timezone parameter since there is also no $locale / $language parameter? I do see use cases for the $timezone parameter, but it feels a bit inconsistent that you can change the timezone but not the language.

No, upstream function is date(). datetime typically stands for DateTime object or related.

👍

No, the intent is to return object set to local time zone. I'll adjust inline doc. Against having argument for it, if something else is needed then object should be manipulated for it.

👍 I think i was confused about the note below the code:

Get a DateTime object for the post. Implementation should default to gmt field as first choice, so this will help with unknown timezone issue.

I mean: why have a $timezone parameter since there is also no $locale / $language parameter?

Because users can already switch locale via interface, which gives implicit handling for it. User timezone is still under discussion though.

Honestly I am not married to having a timezone arg. But at the moment if you want to adjust timezone you need to filter timezone_string, which is cumbersome API for the task.

I think i was confused about the note below the code:

That's about post field, i.e. implementation should read post_date_gmt before post_date. Unrelated to output.

No, the intent is to return object set to local time zone.

For EDD3, we’ve opted not to change any UTC values from the database (to either local or WordPress timezones) so that no reversing is necessary.

The only time we apply any offsets are immediately before output, basically treating it like an escaping function.

This way, all variable values are UTC, and all date/time output caters to the reader.

We plan on doing the same with APIs. Provide UTC values, and let the application decide how to manipulate them.

For EDD3, we’ve opted not to change any UTC values from the database (to either local or WordPress timezones) so that no reversing is necessary.
The only time we apply any offsets are immediately before output, basically treating it like an escaping function.

I am not sure I follow about "reversing". That function will just return a native DateTime object, which represents time internally as Unix timestamp anyway.

Having the object in WP time zone makes more sense to me in WP mechanics, which primarily deals with WP time.

Also going to UTC timezone is easier than going from UTC time zone, which requires fecthing/figuring out local time zone, and potentially user time zone (which is being discussed).

In regards to API personally I'd output timestamps (for which time zone doesn't matter) or RFC3339 (for which time zone is included). Unfortunately WP REST API went with timezone-less local time and possibly missing UTC time, which is quite fragile and needs addressing too.

Also going to UTC timezone is easier than going from UTC time zone, which requires fecthing/figuring out local time zone, and potentially user time zone (which is being discussed).

The problem we discovered with that approach, is there is no way to know which variables floating around during runtime already had an offset applied to them, and it’s easy to accidentally re-apply the offset more than once. Too many WordPress functions misguidingly apply offsets in too many unexpected places.

Going to or from UTC is the same static math either way, but knowing when to do so is impossible without strict rules.

Late-escaping is a good example, because late-date-offsetting would work exactly the same, for the same reasons, and avoiding the same problems (double escaping being bad and all that.)

The problem we discovered with that approach, is there is no way to know which variables floating around during runtime already had an offset applied to them, and it’s easy to accidentally re-apply the offset more than once.

I really don't follow. We are talking DateTime object here. No one should be applying any offsets to it. It is based on a real actual Unix timestamp and it knows how to do timezone math (much better than WordPress does).

Too many WordPress functions misguidingly apply offsets in too many unexpected places.

We are dropping all that shit from core once there is unified timezone object retrieval in place.

Late-escaping is a good example, because late-date-offsetting would work exactly the same

We are done with manual date offsetting. It has to go.

Some updates assuming targeting PHP 5.6 bump:

1. Problem with creating semi–functional timezone objects on PHP <5.5 is gone! wp_timezone() will return fully functional object in all cases.
2. We get immutables! Changed get_post_datetime() signature to return DateTimeImmutable by default with a flag to override.

Dropped the override immutable flag.

Split out wp_timezone_string() to offer as straightforward upgrade from get_option('timezone_string') in existing code, rather than getting object and going back from object to string.

Added current_datetime() from plowing through current_time() issues and limitations.

wp_timezone_string() and wp_timezone() merged for WP 5.3 🎉

current_datetime() merged for WP 5.3

wp_date() merged for WP 5.3

Shelved time tag, since it's quite involved to implement generically as function call, but easy to template.

get_post_datetime(), get_post_timestamp() merged for WP 5.3

And we are done with API (for now)! 🎉