Documentation issue: get_post_time is getting the time when published not when created

[casiepa]

I'm having a doubt with ​https://developer.wordpress.org/reference/functions/get_post_time/ (probably the same with ​https://developer.wordpress.org/reference/functions/get_the_date/)
They both say 'Retrieve the date on which the post was written.', but from some programming I'm doing now it looks more like 'Retrieve the date on which the post was PUBLISHED.'.

Test: create a post in draft or pending and check that date using the function. (I'm doing it with a CPT)

[audrasjb]

Docs: Various date/time functions are returning the date/time the content was published, not written

[audrasjb]

Thanks for raising this issue Pascal!

I updated the following functions/hooks:

• the_date_xml
• the_date
• get_the_date
• get_the_modified_date
• the_time
• get_the_time
• get_post_time
• get_post_modified_time
• the_weekday
• the_weekday_date

[SergeyBiryukov]

This might need some further clarification, as it's not quite clear what "published" means for a draft or pending post.

In my testing:

• For a draft post that never was published, get_the_date() returns the date of the last edit.
• For a post that was previously published, get_the_date() returns the published date.

For both of these cases, the existing docs seem accurate. 51289.diff​ would only be accurate for the second case.

[Rarst]

The current wording is imperfect, but "was published" would imply a post is published. It might be not published. It might be scheduled for the future.

I think it should be neutral wording like "the date of the current post", which is already partially there. It just describes the return without implications about state of the post.

[helen]

I agree this can be worded as "the date of the post" for most of these, a few seem a little tricker (e.g. "The weekday name of the date of the post"?) but I'm confidence somebody with some wordsmithing skills can figure it out :) Punting out of 5.6 for now, strongly encourage some contributions here.

[desrosj]

This one hasn't seen any activity in this release cycle and still needs a patch refresh to address feedback. I'm going to punt, but if a committer has time to review, it can be moved back.

[desrosj]

Since this has not seen any activity during the 5.8 release cycle, I'm punting to Future Release. When a contributor is able to create a new patch, it can be moved back to a numbered milestone.

[azouamauriac]

I think this bug is deeper and more over a word issue. Since WordPress assumes that 'publish date' = 'write date' and save both data in 'post_modified' attribute. I don't think that way to see things is really right. A post can be written without published; so both dates should be handled by different properties.

…ndles dates and times associated with posts. Instead of referring to the "date the post was written," the functions and filter descriptions now refer to the "date of the post." This change likely reflects a move towards greater flexibility in how dates are used, accommodating scenarios where the displayed date might not strictly correspond to the writing date (e.g., scheduled posts, backdated posts, or content where the "date" represents something other than creation).

Here's a breakdown of the changes:

• Function and Filter Descriptions: Docblocks for the_date(), get_the_date(), the_time(), get_the_time(), get_post_time(), the_weekday(), and the_weekday_date() have been updated to reflect the new "date of the post" language. The filters associated with these functions have also received corresponding updates. This change is primarily semantic.

• get_post_time() Docblock Update: The description for get_post_time() is also updated, clarifying that the $format parameter accepts standard PHP date formats or 'G' (Unix timestamp) or 'U' (seconds since the Unix Epoch). The wording emphasizes that this function retrieves the *localized* date of the post.

The changes don't introduce new functionality or modify existing behavior. They clarify the purpose of these functions and make the documentation more accurate and flexible. The shift to "date of the post" acknowledges that the displayed date might have different meanings depending on the context.

[audrasjb]

Hi @pbearne thanks for the PR. This looks good on my side. I spotted a few glitches though. I added them in your PR :)

[pbearne]

fixed

[audrasjb]

In 59691:

Docs: Clarify the purpose of post date/time functions.

This changeset clarifies the purpose of these functions and make the documentation more accurate and flexible. Instead of referring to the "date the post was written," the functions and filter descriptions now refer to the "date of the post." This change accommodates scenarios where the displayed date might not strictly correspond to the writing date (e.g. scheduled posts, backdated posts, or content where the "date" represents something other than creation).

Props casiepa, audrasjb, SergeyBiryukov, Rarst, helen, azouamauriac, pbearne.
Fixes #51289.

committed in https://core.trac.wordpress.org/changeset/59691

[SergeyBiryukov]

In 59692:

Docs: Correct description for the_time(), get_the_time(), and get_post_time().

This aims to avoid confusion with the_date() and get_the_date().

Includes synchronizing the description for the_weekday() and the_weekday_date(), which have very similar functionality, except that the latter will only output the weekday if the current post's weekday is different from the previous one output.

Follow-up to [59691].

See #51289.