id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc
11264	add missing get_the_date() function and use it inside the_date()	jeremyclarke	westi	"== 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. 

"	enhancement	closed	normal	3.0	Date/Time	2.9	normal	fixed	has-patch	jeremyclarke sivel