add missing get_the_date() function and use it inside the_date()

[jeremyclarke]

Problem

Despite the obvious implications of the API as concerns the_* and get_the_* functions, there is currently no get_the_date() function. There is an $echo paremeter for the_date() that can be used to have it return the html output (including $before and $after), but no way to directly fetch the formatted text string.

There are several situations in which get_the_date() would be useful, not the least of which is the matching filter get_the_date which can be used to filter date output without worrying about $before, $after and any other filters that might be running on the_date.

Unlike many of the other the_* functions the_date() is special in that it has the very idiosyncratic feature of only outputting the date string once per day listed. This is the 'feature' that stops the date from showing multiple times with the same day when looping through posts. IMHO this feature, while often handy, is not obvious, and can be very confusing to users who simply want to show the date of the post on every single post (which is redundant at times but makes a lot of sense in a LOT of themes).

Solution

If we could travel back in time I would strongly recommend making this effect optional and making the default use of the_date() show the output every time its called. Even better IMHO would be to leave the_date() alone and create a function called the_date_once() that has the once-per-day effect. Alas my time machine is nowhere near completion, so instead I propose that adding a get_the_date() will help alleviate the issues with the_date() by making it so people wanting to avoid the once-per-day effect can just use echo get_the_date() to show a date for sure.

SO: Add get_the_date() as the source of the date itself. This can be filtered seperately from the_date() and does not have the once-per-day effect.

Implementation

The attached patch is simple and designed to match almost exactly the separation that exists between get_the_time() and the_time().

In /wp-includes/general-template.php I create the get_the_date() function below the_date() and move the actual date generation code into it. Note that the $d argument (date format string) is passed in from the_date() but not the others:

/**
 * Retrieve the date the current $post was written.
 *
 * Unlike the_date() this function will always return the date.
 * Modify output with 'get_the_date' filter.
 *
 * @since 2.9
 *
 * @param string $d Optional. PHP date format defaults to the date_format option if not specified.
 * @return string|null Null if displaying, string if retrieving.
 */
function get_the_date($d='') {
	global $post, $day;
	$the_date = '';

	if ( '' == $d )
		$the_date .= mysql2date(get_option('date_format'), $post->post_date);
	else
		$the_date .= mysql2date($d, $post->post_date);

	return apply_filters('get_the_date', $the_date, $d);
}

This also of course creates the new get_the_date filter.

Then in the_date() I remove the date generation code and replace it with get_the_date($d).

In this patch I also added more information to the phpdoc definition for the_date() to clarify the once-per-day effect and specify the filters that can be used to alter output.

Timing

I'm pretty confident that this change will not break any uses of the_date(). The new system should work exactly like the old one but with more options. Still it might be better to make the change outside of the 2.9 branch, though I think it could safely be added there.

[jeremyclarke]

add get_the_date() function to /wp-includes/general-template.php and use it in the_date()

[westi]

Sounds like an excellent idea.

Good thing to do early in 3.0

Maybe we can come up with a way of making the_date() always output by adding a defaulted argument for the current behaviour which then themes can override.

[jeremyclarke]

Replying to westi:

Maybe we can come up with a way of making the_date() always output by adding a defaulted argument for the current behaviour which then themes can override.

I thought about that for awhile but when you look at the_date() as it currently stands it seems like the only solutions there are insanely ugly:

function the_date($d='', $before='', $after='', $echo = true)

IMHO if it will be on-by-default the $show_once parameter should be early on, probably after $d, but that will kick the hell out of people already using $before and $after. Putting $show_once at the end, on the other hand, feels totally wrong to me. I might be overreacting aesthetically of course. I'd support adding it at the end if you guys are into it, its just obviously not ideal :)

[caesarsgrunt]

I'd add it at the end. Not nice, but it can't really go anywhere else...

Additionally, I fully support the idea of get_the_date().

It should be easy to implement and doesn't affect the UI; couldn't it go into 2.9 ?

[lloydbudd]

Replying to caesarsgrunt:

It should be easy to implement and doesn't affect the UI; couldn't it go into 2.9 ?

I love your enthusiasm! Still change introduces risk. Let's leave anything not on the critical path out and get 2.9 out in time for the holiday season!

[jeremyclarke]

Hey, let me know if this needs anything else to get into 3.0, seems like the patch is probably still good. Thanks.

[Viper007Bond]

This was fixed in [12917]