wp_get_archives

Display archive links based on type and format.

Description

(string|void) wp_get_archives( (string) $args = '' ); 

Returns (string|void)

String when retrieving.

Parameters (1)

0. $args — Optional. (string) => ''
Default archive links arguments. Optional.

Options

  • type (string) => 'monthly'

    Type of archive to retrieve. Accepts daily,, weekly., monthly , yearly, postbypost, or alpha. Both postbypost and alpha display the same archive link list as well as post titles instead of displaying dates. The difference between the two is that alpha will order by post title and postbypost will order by post date.

  • limit (string|int) => (no limit)

    Number of links to limit the query to.

  • format (string) => 'html'

    Format each link should take using the $before and $after args. Accepts link ('' tag), option ('

  • ' tag), or a custom format, which generates a link anchor with $before preceding and $after succeeding.

  • before (string) => ''

    Markup to prepend to the beginning of each link.

  • after (string) => ''

    Markup to append to the end of each link.

  • show_post_count (bool) => false

    Whether to display the post count alongside the link.

  • echo (bool|int) => 1

    Whether to echo or return the links list.

  • order (string) => 'DESC'

    Whether to use ascending or descending order. Accepts ASC,, or DESC..

  • array(
    
        /**
         * Type of archive to retrieve. Accepts 'daily', 'weekly', 'monthly', 'yearly',
         * 'postbypost', or 'alpha'. Both 'postbypost' and 'alpha' display the same archive link list
         * as well as post titles instead of displaying dates. The difference between the two is that
         * 'alpha' will order by post title and 'postbypost' will order by post date.
         *
         * @type string
         * @default 'monthly'
         */
        'type' => 'monthly',
    
        /**
         * Number of links to limit the query to.
         *
         * @type string|int
         * @default (no limit)
         */
        'limit' => (no limit),
    
        /**
         * Format each link should take using the $before and $after args. Accepts 'link' (`` tag),
         * 'option' (`` tag), 'html' (`` tag), or a custom format, which generates a link anchor with
         * $before preceding and $after succeeding.
         *
         * @type string
         * @default 'html'
         */
        'format' => 'html',
    
        /**
         * Markup to prepend to the beginning of each link.
         *
         * @type string
         * @default ''
         */
        'before' => '',
    
        /**
         * Markup to append to the end of each link.
         *
         * @type string
         * @default ''
         */
        'after' => '',
    
        /**
         * Whether to display the post count alongside the link.
         *
         * @type bool
         * @default false
         */
        'show_post_count' => false,
    
        /**
         * Whether to echo or return the links list.
         *
         * @type bool|int
         * @default 1
         */
        'echo' => 1,
    
        /**
         * Whether to use ascending or descending order. Accepts 'ASC', or 'DESC'.
         *
         * @type string
         * @default 'DESC'
         */
        'order' => 'DESC'
    );        


    Usage

    1. if ( !function_exists( 'wp_get_archives' ) ) { 
    2. require_once ABSPATH . WPINC . '/general-template.php'; 
    3.  
    4. // Default archive links arguments. Optional. 
    5. $args = array( 
    6. 'type' => 'monthly', 
    7. 'limit' => (no limit), 
    8. 'format' => 'html', 
    9. 'before' => '', 
    10. 'after' => '', 
    11. 'show_post_count' => false, 
    12. 'echo' => 1, 
    13. 'order' => 'DESC' 
    14. ); 
    15.  
    16. // NOTICE! Understand what this does before running. 
    17. $result = wp_get_archives($args); 
    18.  

    Defined (1)

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

    /wp-includes/general-template.php  
    1. function wp_get_archives( $args = '' ) { 
    2. global $wpdb, $wp_locale; 
    3.  
    4. $defaults = array( 
    5. 'type' => 'monthly', 'limit' => '',  
    6. 'format' => 'html', 'before' => '',  
    7. 'after' => '', 'show_post_count' => false,  
    8. 'echo' => 1, 'order' => 'DESC',  
    9. 'post_type' => 'post' 
    10. ); 
    11.  
    12. $r = wp_parse_args( $args, $defaults ); 
    13.  
    14. $post_type_object = get_post_type_object( $r['post_type'] ); 
    15. if ( ! is_post_type_viewable( $post_type_object ) ) { 
    16. return; 
    17. $r['post_type'] = $post_type_object->name; 
    18.  
    19. if ( '' == $r['type'] ) { 
    20. $r['type'] = 'monthly'; 
    21.  
    22. if ( ! empty( $r['limit'] ) ) { 
    23. $r['limit'] = absint( $r['limit'] ); 
    24. $r['limit'] = ' LIMIT ' . $r['limit']; 
    25.  
    26. $order = strtoupper( $r['order'] ); 
    27. if ( $order !== 'ASC' ) { 
    28. $order = 'DESC'; 
    29.  
    30. // this is what will separate dates on weekly archive links 
    31. $archive_week_separator = '–'; 
    32.  
    33. $sql_where = $wpdb->prepare( "WHERE post_type = %s AND post_status = 'publish'", $r['post_type'] ); 
    34.  
    35. /** 
    36. * Filters the SQL WHERE clause for retrieving archives. 
    37. * @since 2.2.0 
    38. * @param string $sql_where Portion of SQL query containing the WHERE clause. 
    39. * @param array $r An array of default arguments. 
    40. */ 
    41. $where = apply_filters( 'getarchives_where', $sql_where, $r ); 
    42.  
    43. /** 
    44. * Filters the SQL JOIN clause for retrieving archives. 
    45. * @since 2.2.0 
    46. * @param string $sql_join Portion of SQL query containing JOIN clause. 
    47. * @param array $r An array of default arguments. 
    48. */ 
    49. $join = apply_filters( 'getarchives_join', '', $r ); 
    50.  
    51. $output = ''; 
    52.  
    53. $last_changed = wp_cache_get_last_changed( 'posts' ); 
    54.  
    55. $limit = $r['limit']; 
    56.  
    57. if ( 'monthly' == $r['type'] ) { 
    58. $query = "SELECT YEAR(post_date) AS `year`, MONTH(post_date) AS `month`, count(ID) as posts FROM $wpdb->posts $join $where GROUP BY YEAR(post_date), MONTH(post_date) ORDER BY post_date $order $limit"; 
    59. $key = md5( $query ); 
    60. $key = "wp_get_archives:$key:$last_changed"; 
    61. if ( ! $results = wp_cache_get( $key, 'posts' ) ) { 
    62. $results = $wpdb->get_results( $query ); 
    63. wp_cache_set( $key, $results, 'posts' ); 
    64. if ( $results ) { 
    65. $after = $r['after']; 
    66. foreach ( (array) $results as $result ) { 
    67. $url = get_month_link( $result->year, $result->month ); 
    68. if ( 'post' !== $r['post_type'] ) { 
    69. $url = add_query_arg( 'post_type', $r['post_type'], $url ); 
    70. /** translators: 1: month name, 2: 4-digit year */ 
    71. $text = sprintf( __( '%1$s %2$d' ), $wp_locale->get_month( $result->month ), $result->year ); 
    72. if ( $r['show_post_count'] ) { 
    73. $r['after'] = ' (' . $result->posts . ')' . $after; 
    74. $output .= get_archives_link( $url, $text, $r['format'], $r['before'], $r['after'] ); 
    75. } elseif ( 'yearly' == $r['type'] ) { 
    76. $query = "SELECT YEAR(post_date) AS `year`, count(ID) as posts FROM $wpdb->posts $join $where GROUP BY YEAR(post_date) ORDER BY post_date $order $limit"; 
    77. $key = md5( $query ); 
    78. $key = "wp_get_archives:$key:$last_changed"; 
    79. if ( ! $results = wp_cache_get( $key, 'posts' ) ) { 
    80. $results = $wpdb->get_results( $query ); 
    81. wp_cache_set( $key, $results, 'posts' ); 
    82. if ( $results ) { 
    83. $after = $r['after']; 
    84. foreach ( (array) $results as $result) { 
    85. $url = get_year_link( $result->year ); 
    86. if ( 'post' !== $r['post_type'] ) { 
    87. $url = add_query_arg( 'post_type', $r['post_type'], $url ); 
    88. $text = sprintf( '%d', $result->year ); 
    89. if ( $r['show_post_count'] ) { 
    90. $r['after'] = ' (' . $result->posts . ')' . $after; 
    91. $output .= get_archives_link( $url, $text, $r['format'], $r['before'], $r['after'] ); 
    92. } elseif ( 'daily' == $r['type'] ) { 
    93. $query = "SELECT YEAR(post_date) AS `year`, MONTH(post_date) AS `month`, DAYOFMONTH(post_date) AS `dayofmonth`, count(ID) as posts FROM $wpdb->posts $join $where GROUP BY YEAR(post_date), MONTH(post_date), DAYOFMONTH(post_date) ORDER BY post_date $order $limit"; 
    94. $key = md5( $query ); 
    95. $key = "wp_get_archives:$key:$last_changed"; 
    96. if ( ! $results = wp_cache_get( $key, 'posts' ) ) { 
    97. $results = $wpdb->get_results( $query ); 
    98. wp_cache_set( $key, $results, 'posts' ); 
    99. if ( $results ) { 
    100. $after = $r['after']; 
    101. foreach ( (array) $results as $result ) { 
    102. $url = get_day_link( $result->year, $result->month, $result->dayofmonth ); 
    103. if ( 'post' !== $r['post_type'] ) { 
    104. $url = add_query_arg( 'post_type', $r['post_type'], $url ); 
    105. $date = sprintf( '%1$d-%2$02d-%3$02d 00:00:00', $result->year, $result->month, $result->dayofmonth ); 
    106. $text = mysql2date( get_option( 'date_format' ), $date ); 
    107. if ( $r['show_post_count'] ) { 
    108. $r['after'] = ' (' . $result->posts . ')' . $after; 
    109. $output .= get_archives_link( $url, $text, $r['format'], $r['before'], $r['after'] ); 
    110. } elseif ( 'weekly' == $r['type'] ) { 
    111. $week = _wp_mysql_week( '`post_date`' ); 
    112. $query = "SELECT DISTINCT $week AS `week`, YEAR( `post_date` ) AS `yr`, DATE_FORMAT( `post_date`, '%Y-%m-%d' ) AS `yyyymmdd`, count( `ID` ) AS `posts` FROM `$wpdb->posts` $join $where GROUP BY $week, YEAR( `post_date` ) ORDER BY `post_date` $order $limit"; 
    113. $key = md5( $query ); 
    114. $key = "wp_get_archives:$key:$last_changed"; 
    115. if ( ! $results = wp_cache_get( $key, 'posts' ) ) { 
    116. $results = $wpdb->get_results( $query ); 
    117. wp_cache_set( $key, $results, 'posts' ); 
    118. $arc_w_last = ''; 
    119. if ( $results ) { 
    120. $after = $r['after']; 
    121. foreach ( (array) $results as $result ) { 
    122. if ( $result->week != $arc_w_last ) { 
    123. $arc_year = $result->yr; 
    124. $arc_w_last = $result->week; 
    125. $arc_week = get_weekstartend( $result->yyyymmdd, get_option( 'start_of_week' ) ); 
    126. $arc_week_start = date_i18n( get_option( 'date_format' ), $arc_week['start'] ); 
    127. $arc_week_end = date_i18n( get_option( 'date_format' ), $arc_week['end'] ); 
    128. $url = add_query_arg( array( 'm' => $arc_year, 'w' => $result->week, ), home_url( '/' ) ); 
    129. if ( 'post' !== $r['post_type'] ) { 
    130. $url = add_query_arg( 'post_type', $r['post_type'], $url ); 
    131. $text = $arc_week_start . $archive_week_separator . $arc_week_end; 
    132. if ( $r['show_post_count'] ) { 
    133. $r['after'] = ' (' . $result->posts . ')' . $after; 
    134. $output .= get_archives_link( $url, $text, $r['format'], $r['before'], $r['after'] ); 
    135. } elseif ( ( 'postbypost' == $r['type'] ) || ('alpha' == $r['type'] ) ) { 
    136. $orderby = ( 'alpha' == $r['type'] ) ? 'post_title ASC ' : 'post_date DESC, ID DESC '; 
    137. $query = "SELECT * FROM $wpdb->posts $join $where ORDER BY $orderby $limit"; 
    138. $key = md5( $query ); 
    139. $key = "wp_get_archives:$key:$last_changed"; 
    140. if ( ! $results = wp_cache_get( $key, 'posts' ) ) { 
    141. $results = $wpdb->get_results( $query ); 
    142. wp_cache_set( $key, $results, 'posts' ); 
    143. if ( $results ) { 
    144. foreach ( (array) $results as $result ) { 
    145. if ( $result->post_date != '0000-00-00 00:00:00' ) { 
    146. $url = get_permalink( $result ); 
    147. if ( $result->post_title ) { 
    148. /** This filter is documented in wp-includes/post-template.php */ 
    149. $text = strip_tags( apply_filters( 'the_title', $result->post_title, $result->ID ) ); 
    150. } else { 
    151. $text = $result->ID; 
    152. $output .= get_archives_link( $url, $text, $r['format'], $r['before'], $r['after'] ); 
    153. if ( $r['echo'] ) { 
    154. echo $output; 
    155. } else { 
    156. return $output;