[wp-trac] [WordPress Trac] #36171: Proposed clean up of get_the_category_list() and link filter

[WordPress Trac]

#36171: Proposed clean up of get_the_category_list() and link filter
--------------------------+-----------------------------
 Reporter:  pietergoosen  |      Owner:
     Type:  enhancement   |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Formatting    |    Version:  4.4.2
 Severity:  normal        |   Keywords:
  Focuses:  performance   |
--------------------------+-----------------------------
 The current source code of the {{{get_the_category_list()}}} function is
 quite messy and there is also a lot of duplicate code which we can avoid.

 Also, on a micro optimization level, in stead of passing the category ID
 to {{{get_category_link()}}}, we can pass the whole category object. Doing
 this will avoid the extra overhead of having to get the complete category
 object from the term cache.

 There is also no filter to filter each category link on category level, we
 only have the {{{the_category}}} filter which filters the string of links.
 We have being receiving a couple of questions on
 wordpress.stackexchange.com regarding filtering these category links
 according to category. [http://wordpress.stackexchange.com/q/219554/31545
 Here] is such one question.

 My proposal is included in my code, a filter called
 {{{the_category_list_links}}} which we can use to filter each category
 link individually according to the category.  One such use-case of the
 filter can look something like

 {{{
 add_filter( 'the_category_list_links', function ( $the_link_list,
 $category, $cat_parents )
 {
         $category_color = get_field( 'category_color', $category );
         if ( !$category_color )
                 return $the_link_list;

         $the_link_list = str_replace( '<a', '<a style="color:' .
 $category_color . '"', $the_link_list );

         return $the_link_list;
 }, 10, 3 );
 }}}

 On initial testing, I can confirm that my code is slightly faster that the
 current code, and the new {{{the_category_list_links}}} filter is working
 as intended

 Here is the proposed cleanup

 {{{
 /**
  * Retrieve category list in either HTML list or custom format.
  *
  * @since 1.5.1
  *
  * @global WP_Rewrite $wp_rewrite
  *
  * @param string $separator Optional, default is empty string. Separator
 for between the categories.
  * @param string $parents Optional. How to display the parents.
  * @param int $post_id Optional. Post ID to retrieve categories.
  * @return string
  */
 function get_the_category_list( $separator = '', $parents = '', $post_id =
 false )
 {
         global $wp_rewrite;

         if ( ! is_object_in_taxonomy( get_post_type( $post_id ),
 'category' ) ) {
                 /** This filter is documented in wp-includes/category-
 template.php */
                 return apply_filters( 'the_category', '', $separator,
 $parents );
         }

         /**
          * Filter the categories before building the category list.
          *
          * @since 4.4.0
          *
          * @param array    $categories An array of the post's categories.
          * @param int|bool $post_id    ID of the post we're retrieving
 categories for. When `false`, we assume the
          *                             current post in the loop.
          */
         $categories = apply_filters( 'the_category_list',
 get_the_category( $post_id ), $post_id );

         if ( empty( $categories ) ) {
                 /** This filter is documented in wp-includes/category-
 template.php */
                 return apply_filters( 'the_category', __( 'Uncategorized'
 ), $separator, $parents );
         }

         $rel = ( is_object( $wp_rewrite ) &&
 $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' :
 'rel="category"';

         $links = array();
         foreach ( $categories as $category ) {
                 /**
                  * Break the link for better link building
                  */
                 $start_link = '<a href="' . esc_url( get_category_link(
 $category->term_id ) ) . '" ' . $rel . '>';
                 $end_link   = $category->name . '</a>';

                 /**
                  * Build the category links
                  */
                 $the_link_list = '';
                 switch ( strtolower( $parents ) ) {
                         case 'multiple':
                                 $cat_parents   = $category->parent ?
 get_category_parents( $category->parent, true, $separator ) : '';
                                 $the_link_list = $cat_parents . ' ' .
 $start_link . $end_link;
                                 break;
                         case 'single':
                                 $cat_parents   = $category->parent ?
 get_category_parents( $category->parent, false, $separator ) : '';
                                 $the_link_list = $start_link .
 $cat_parents . $end_link;
                                 break;
                         case '':
                         default:
                                 $the_link_list = $start_link . $end_link;
                 }

                 /**
                  * Filter the category links on category level.
                  *
                  * @since X.X.X
                  *
                  * @param string $the_link_list Post category link.
                  * @param object $category      The current category
 object
                  * @param $cat_parents          Link list of parents of
 the current category
                  */
                 $links[] = apply_filters( 'the_category_list_links',
 $the_link_list, $category, $cat_parents );
         }

         $thelist = '';
         if( '' === $separator ) {
                 $thelist .= '<ul class="post-categories">';
                         $thelist .= "\n\t<li>";

                                 $thelist .= implode( "</li>\n\t<li>",
 $links );

                         $thelist .= '</li>';
                 $thelist .= '</ul>';
         } else {
                 $thelist .= implode( $separator, $links );
         }

         /**
          * Filter the category or list of categories.
          *
          * @since 1.2.0
          *
          * @param array  $thelist   List of categories for the current
 post.
          * @param string $separator Separator used between the categories.
          * @param string $parents   How to display the category parents.
 Accepts 'multiple',
          *                          'single', or empty.
          */
         return apply_filters( 'the_category', $thelist, $separator,
 $parents );
 }
 }}}

--
Ticket URL: <https://core.trac.wordpress.org/ticket/36171>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform