[wp-trac] [WordPress Trac] #11264: add missing get_the_date() function and use it inside the_date()

[WordPress Trac]

#11264: add missing get_the_date() function and use it inside the_date()
--------------------------+-------------------------------------------------
 Reporter:  jeremyclarke  |       Owner:  jeremyclarke
     Type:  enhancement   |      Status:  new         
 Priority:  normal        |   Milestone:  Unassigned  
Component:  Date/Time     |     Version:  2.9         
 Severity:  normal        |    Keywords:  has-patch   
--------------------------+-------------------------------------------------
 == 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.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/11264>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software