get_the_category_list

Retrieve category list in either HTML list or custom format.

Description

(string) get_the_category_list( (string) $separator = '', (string) $parents = '', (bool) $post_id = false ); 

Returns (string)

Parameters (3)

0. $separator — Optional. (string) => ''
Optional, default is empty string. Separator for between the categories.
1. $parents — Optional. (string) => ''
How to display the parents.
2. $post_id — Optional. (bool) => false
Post ID to retrieve categories.

Usage

  1. if ( !function_exists( 'get_the_category_list' ) ) { 
  2.     require_once ABSPATH . WPINC . '/category-template.php'; 
  3. } 
  4.   
  5. // Optional, default is empty string. Separator for between the categories. 
  6. $separator = ''; 
  7.   
  8. // Optional. How to display the parents. 
  9. $parents = ''; 
  10.   
  11. // Optional. Post ID to retrieve categories. 
  12. $post_id = false; 
  13.   
  14. // NOTICE! Understand what this does before running. 
  15. $result = get_the_category_list($separator, $parents, $post_id); 
  16.     

Defined (1)

The function is defined in the following location(s).

/wp-includes/category-template.php  
  1. function get_the_category_list( $separator = '', $parents='', $post_id = false ) { 
  2.     global $wp_rewrite; 
  3.     if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) { 
  4.         /** This filter is documented in wp-includes/category-template.php */ 
  5.         return apply_filters( 'the_category', '', $separator, $parents ); 
  6.     } 
  7.  
  8.     /** 
  9.      * Filters the categories before building the category list. 
  10.      * 
  11.      * @since 4.4.0 
  12.      * 
  13.      * @param array    $categories An array of the post's categories. 
  14.      * @param int|bool $post_id    ID of the post we're retrieving categories for. When `false`, we assume the 
  15.      *                             current post in the loop. 
  16.      */ 
  17.     $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id ); 
  18.  
  19.     if ( empty( $categories ) ) { 
  20.         /** This filter is documented in wp-includes/category-template.php */ 
  21.         return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents ); 
  22.     } 
  23.  
  24.     $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"'; 
  25.  
  26.     $thelist = ''; 
  27.     if ( '' == $separator ) { 
  28.         $thelist .= '<ul class="post-categories">'; 
  29.         foreach ( $categories as $category ) { 
  30.             $thelist .= "\n\t<li>"; 
  31.             switch ( strtolower( $parents ) ) { 
  32.                 case 'multiple': 
  33.                     if ( $category->parent ) 
  34.                         $thelist .= get_category_parents( $category->parent, true, $separator ); 
  35.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a></li>'; 
  36.                     break; 
  37.                 case 'single': 
  38.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '"  ' . $rel . '>'; 
  39.                     if ( $category->parent ) 
  40.                         $thelist .= get_category_parents( $category->parent, false, $separator ); 
  41.                     $thelist .= $category->name.'</a></li>'; 
  42.                     break; 
  43.                 case '': 
  44.                 default: 
  45.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a></li>'; 
  46.             } 
  47.         } 
  48.         $thelist .= '</ul>'; 
  49.     } else { 
  50.         $i = 0; 
  51.         foreach ( $categories as $category ) { 
  52.             if ( 0 < $i ) 
  53.                 $thelist .= $separator; 
  54.             switch ( strtolower( $parents ) ) { 
  55.                 case 'multiple': 
  56.                     if ( $category->parent ) 
  57.                         $thelist .= get_category_parents( $category->parent, true, $separator ); 
  58.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a>'; 
  59.                     break; 
  60.                 case 'single': 
  61.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>'; 
  62.                     if ( $category->parent ) 
  63.                         $thelist .= get_category_parents( $category->parent, false, $separator ); 
  64.                     $thelist .= "$category->name</a>"; 
  65.                     break; 
  66.                 case '': 
  67.                 default: 
  68.                     $thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name.'</a>'; 
  69.             } 
  70.             ++$i; 
  71.         } 
  72.     } 
  73.  
  74.     /** 
  75.      * Filters the category or list of categories. 
  76.      * 
  77.      * @since 1.2.0 
  78.      * 
  79.      * @param array  $thelist   List of categories for the current post. 
  80.      * @param string $separator Separator used between the categories. 
  81.      * @param string $parents   How to display the category parents. Accepts 'multiple',  
  82.      *                          'single', or empty. 
  83.      */ 
  84.     return apply_filters( 'the_category', $thelist, $separator, $parents ); 
  85. }