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. // Optional, default is empty string. Separator for between the categories. 
  5. $separator = ''; 
  6.  
  7. // Optional. How to display the parents. 
  8. $parents = ''; 
  9.  
  10. // Optional. Post ID to retrieve categories. 
  11. $post_id = false; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = get_the_category_list($separator, $parents, $post_id); 
  15.  

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