Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New functions to add to API #4

Open
Rarst opened this Issue Jul 5, 2018 · 10 comments

Comments

3 participants
@Rarst
Copy link
Owner

commented Jul 5, 2018

This is a broad collection of what I envision to be added to Date/Time API.


wp_timezone()

/**
 * Retrieve the current settings timezone as `DateTimeZone` object.
 *
 * @return DateTimeZone Timezone object.
 */
function wp_timezone() {}

We badly need unified timezone retrieval (from gmt_offset or timezone_string either) to get rid of offset math.


wp_date()

/**
 * Retrieve the date, in localized format.
 *
 * @param string       $format    PHP date format.
 * @param int          $timestamp Optional. Unix timestamp. Defaults to current time.
 * @param DateTimeZone $timezone  Optional. Timezone to output result in. Defaults to timezone from WordPress settings.
 *
 * @return string The date, translated if locale specifies it.
 */
function wp_date( $format, $timestamp = null, $timezone = null ) {}

date_i18n() replacement that works of actual real Unix timestamps and also a little more flexible about timezone.


get_post_datetime()

/**
 * Retrieve post published or modified time as `DateTimeImmutable` object instance.
 *
 * Object will be set to timezone from WordPress settings.
 *
 * @param WP_Post|array|int $post      Optional. WordPress post instance or ID. Defaults to the global `$post`.
 * @param string            $field     Optional. Post field to use. Can be `date` or `date_modified`.
 *
 * @return DateTimeImmutable Time object.
 */
function get_post_datetime( $post = null, $field = 'date' ) {}

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


get_post_timestamp()

/**
 * Retrieve post published or modified time as Unix timestamp.
 *
 * @param WP_Post|array|int $post  Optional. WordPress post instance or ID. Defaults to the global `$post`.
 * @param string            $field Optional. Post field to use. Can be `date` or `date_modified`.
 *
 * @return int Unix timestamp.
 */
function get_post_timestamp( $post = null, $field = 'date' ) {}

Wrapper for datetime one. We need to deprecated G and U formats in existing functions (so around lower level get_post_time()) and point to this one as replacement.


the_time_tag()

/**
 * Display the time at which the post was written, in a form of HTML `<time />` tag.
 *
 * @param string $format PHP date format.
 */
function the_time_tag( $format = '' ) {}

Just a small helper for better machine–readable output, was requested before.

@Rarst Rarst added the organization label Jul 5, 2018

@Rarst Rarst added this to Discussion in wp_date via automation Jul 5, 2018

@Rarst Rarst changed the title New function to add to API New functions to add to API Jul 5, 2018

@remcotolsma

This comment has been minimized.

Copy link

commented Jul 6, 2018

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
@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jul 6, 2018

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.

@remcotolsma

This comment has been minimized.

Copy link

commented Jul 6, 2018

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.

@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jul 6, 2018

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.

@JJJ

This comment has been minimized.

Copy link

commented Jul 6, 2018

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.

@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jul 6, 2018

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.

@JJJ

This comment has been minimized.

Copy link

commented Jul 6, 2018

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.)

@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jul 6, 2018

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.

@Rarst Rarst self-assigned this Nov 8, 2018

@Rarst Rarst pinned this issue Dec 14, 2018

@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jan 21, 2019

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.
@Rarst

This comment has been minimized.

Copy link
Owner Author

commented Jan 22, 2019

Dropped the override immutable flag.

@Rarst Rarst referenced this issue Mar 19, 2019

Open

wp_date roadmap #1

1 of 8 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.