paginate_links

Retrieve paginated link for archive post pages.

Description

(array|string|void) paginate_links( (string) $args = '' ); 

Technically, the function can be used to create paginated link list for any area. The base argument is used to reference the url, which will be used to create the paginated links. The format. argument is then used for replacing the page number. It is however, most likely and by default, to be used on the archive post pages.

The type argument controls format of the returned value. The default is 'plain', which is just a string with the links separated by a newline character. The other possible values are either array or list. The array value will return an array of the paginated link list to offer full control of display. The list value will place all of the paginated links in an unordered HTML list.

The total argument is the total amount of pages and is an integer. The 'current' argument is the current page number and is also an integer.

An example of the base argument is http://example.com/all_posts.php%_% and the %_% is required. The %_% will be replaced by the contents of in the format. argument. An example for the format. argument is ?page=%#% and the %#% is also required. The %#% will be replaced with the page number.

You can include the previous and next links in the list by setting the 'prev_next' argument to true, which it is by default. You can set the previous text, by using the prev_text argument. You can set the next text by setting the next_text argument.

If the show_all argument is set to true, then it will show all of the pages instead of a short list of the pages near the current page. By default, the show_all is set to false and controlled by the end_size and mid_size arguments. The end_size argument is how many numbers on either the start and the end list edges, by default is 1. The mid_size argument is how many numbers to either side of current page, but not including current page.

It is possible to add query vars to the link by using the add_args argument and see add_query_arg() for more information.

The before_page_number and after_page_number arguments allow users to augment the links themselves. Typically this might be to add context to the numbered links so that screen reader users understand what the links are for. The text strings are added before and after the page number - within the anchor tag.

Returns (array|string|void)

String of page links or array of page links.

Parameters (1)

0. $args — Optional. (string) => ''
Array or string of arguments for generating paginated links for archives.

Options

  • base (string) => ''

    Base of the paginated url.

  • format (string) => ''

    Format for the pagination structure.

  • total (int) => 'is the value WP_Query'

    The total amount of pages.

  • current (int) => 'paged'

    The current page number.

  • show_all (bool) => false

    Whether to show all pages.

  • end_size (int) => 1

    How many numbers on either the start and the end list edges.

  • mid_size (int) => 2

    How many numbers to either side of the current pages.

  • prev_next (bool) => true

    Whether to include the previous and next links in the list.

  • prev_text (bool) => '« Previous'

    The previous page text.

  • next_text (bool) => 'Next »'

    The next page text.

  • type (string) => 'plain'

    Controls format of the returned value. Possible values are plain,, array and list..

  • add_args (array) => false

    An array of query args to add.

  • add_fragment (string) => ''

    A string to append to each link.

  • before_page_number (string) => ''

    A string to appear before the page number.

array(

    /**
     * Base of the paginated url.
     *
     * @type string
     * @default ''
     */
    'base' => '',

    /**
     * Format for the pagination structure.
     *
     * @type string
     * @default ''
     */
    'format' => '',

    /**
     * The total amount of pages.
     *
     * @type int
     * @default 'is the value WP_Query'
     */
    'total' => 'is the value WP_Query',

    /**
     * The current page number.
     *
     * @type int
     * @default 'paged'
     */
    'current' => 'paged',

    /**
     * Whether to show all pages.
     *
     * @type bool
     * @default false
     */
    'show_all' => false,

    /**
     * How many numbers on either the start and the end list edges.
     *
     * @type int
     * @default 1
     */
    'end_size' => 1,

    /**
     * How many numbers to either side of the current pages.
     *
     * @type int
     * @default 2
     */
    'mid_size' => 2,

    /**
     * Whether to include the previous and next links in the list.
     *
     * @type bool
     * @default true
     */
    'prev_next' => true,

    /**
     * The previous page text.
     *
     * @type bool
     * @default '« Previous'
     */
    'prev_text' => '« Previous',

    /**
     * The next page text.
     *
     * @type bool
     * @default 'Next »'
     */
    'next_text' => 'Next »',

    /**
     * Controls format of the returned value. Possible values are 'plain', 'array' and 'list'.
     *
     * @type string
     * @default 'plain'
     */
    'type' => 'plain',

    /**
     * An array of query args to add.
     *
     * @type array
     * @default false
     */
    'add_args' => false,

    /**
     * A string to append to each link.
     *
     * @type string
     * @default ''
     */
    'add_fragment' => '',

    /**
     * A string to appear before the page number.
     *
     * @type string
     * @default ''
     */
    'before_page_number' => ''
);        


Usage

  1. if ( !function_exists( 'paginate_links' ) ) { 
  2. require_once ABSPATH . WPINC . '/general-template.php'; 
  3.  
  4. // Optional. Array or string of arguments for generating paginated links for archives. 
  5. $args = array( 
  6. 'base' => '', 
  7. 'format' => '', 
  8. 'total' => 'is the value WP_Query', 
  9. 'current' => 'paged', 
  10. 'show_all' => false, 
  11. 'end_size' => 1, 
  12. 'mid_size' => 2, 
  13. 'prev_next' => true, 
  14. 'prev_text' => '« Previous', 
  15. 'next_text' => 'Next »', 
  16. 'type' => 'plain', 
  17. 'add_args' => false, 
  18. 'add_fragment' => '', 
  19. 'before_page_number' => '' 
  20. ); 
  21.  
  22. // NOTICE! Understand what this does before running. 
  23. $result = paginate_links($args); 
  24.  

Defined (1)

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

/wp-includes/general-template.php  
  1. function paginate_links( $args = '' ) { 
  2. global $wp_query, $wp_rewrite; 
  3.  
  4. // Setting up default values based on the current URL. 
  5. $pagenum_link = html_entity_decode( get_pagenum_link() ); 
  6. $url_parts = explode( '?', $pagenum_link ); 
  7.  
  8. // Get max pages and current page out of the current query, if available. 
  9. $total = isset( $wp_query->max_num_pages ) ? $wp_query->max_num_pages : 1; 
  10. $current = get_query_var( 'paged' ) ? intval( get_query_var( 'paged' ) ) : 1; 
  11.  
  12. // Append the format placeholder to the base URL. 
  13. $pagenum_link = trailingslashit( $url_parts[0] ) . '%_%'; 
  14.  
  15. // URL base depends on permalink settings. 
  16. $format = $wp_rewrite->using_index_permalinks() && ! strpos( $pagenum_link, 'index.php' ) ? 'index.php/' : ''; 
  17. $format .= $wp_rewrite->using_permalinks() ? user_trailingslashit( $wp_rewrite->pagination_base . '/%#%', 'paged' ) : '?paged=%#%'; 
  18.  
  19. $defaults = array( 
  20. 'base' => $pagenum_link, // http://example.com/all_posts.php%_% : %_% is replaced by format (below) 
  21. 'format' => $format, // ?page=%#% : %#% is replaced by the page number 
  22. 'total' => $total,  
  23. 'current' => $current,  
  24. 'show_all' => false,  
  25. 'prev_next' => true,  
  26. 'prev_text' => __('« Previous'),  
  27. 'next_text' => __('Next »'),  
  28. 'end_size' => 1,  
  29. 'mid_size' => 2,  
  30. 'type' => 'plain',  
  31. 'add_args' => array(), // array of query args to add 
  32. 'add_fragment' => '',  
  33. 'before_page_number' => '',  
  34. 'after_page_number' => '' 
  35. ); 
  36.  
  37. $args = wp_parse_args( $args, $defaults ); 
  38.  
  39. if ( ! is_array( $args['add_args'] ) ) { 
  40. $args['add_args'] = array(); 
  41.  
  42. // Merge additional query vars found in the original URL into 'add_args' array. 
  43. if ( isset( $url_parts[1] ) ) { 
  44. // Find the format argument. 
  45. $format = explode( '?', str_replace( '%_%', $args['format'], $args['base'] ) ); 
  46. $format_query = isset( $format[1] ) ? $format[1] : ''; 
  47. wp_parse_str( $format_query, $format_args ); 
  48.  
  49. // Find the query args of the requested URL. 
  50. wp_parse_str( $url_parts[1], $url_query_args ); 
  51.  
  52. // Remove the format argument from the array of query arguments, to avoid overwriting custom format. 
  53. foreach ( $format_args as $format_arg => $format_arg_value ) { 
  54. unset( $url_query_args[ $format_arg ] ); 
  55.  
  56. $args['add_args'] = array_merge( $args['add_args'], urlencode_deep( $url_query_args ) ); 
  57.  
  58. // Who knows what else people pass in $args 
  59. $total = (int) $args['total']; 
  60. if ( $total < 2 ) { 
  61. return; 
  62. $current = (int) $args['current']; 
  63. $end_size = (int) $args['end_size']; // Out of bounds? Make it the default. 
  64. if ( $end_size < 1 ) { 
  65. $end_size = 1; 
  66. $mid_size = (int) $args['mid_size']; 
  67. if ( $mid_size < 0 ) { 
  68. $mid_size = 2; 
  69. $add_args = $args['add_args']; 
  70. $r = ''; 
  71. $page_links = array(); 
  72. $dots = false; 
  73.  
  74. if ( $args['prev_next'] && $current && 1 < $current ) : 
  75. $link = str_replace( '%_%', 2 == $current ? '' : $args['format'], $args['base'] ); 
  76. $link = str_replace( '%#%', $current - 1, $link ); 
  77. if ( $add_args ) 
  78. $link = add_query_arg( $add_args, $link ); 
  79. $link .= $args['add_fragment']; 
  80.  
  81. /** 
  82. * Filters the paginated links for the given archive pages. 
  83. * @since 3.0.0 
  84. * @param string $link The paginated link URL. 
  85. */ 
  86. $page_links[] = '<a class="prev page-numbers" href="' . esc_url( apply_filters( 'paginate_links', $link ) ) . '">' . $args['prev_text'] . '</a>'; 
  87. endif; 
  88. for ( $n = 1; $n <= $total; $n++ ) : 
  89. if ( $n == $current ) : 
  90. $page_links[] = "<span class='page-numbers current'>" . $args['before_page_number'] . number_format_i18n( $n ) . $args['after_page_number'] . "</span>"; 
  91. $dots = true; 
  92. else : 
  93. if ( $args['show_all'] || ( $n <= $end_size || ( $current && $n >= $current - $mid_size && $n <= $current + $mid_size ) || $n > $total - $end_size ) ) : 
  94. $link = str_replace( '%_%', 1 == $n ? '' : $args['format'], $args['base'] ); 
  95. $link = str_replace( '%#%', $n, $link ); 
  96. if ( $add_args ) 
  97. $link = add_query_arg( $add_args, $link ); 
  98. $link .= $args['add_fragment']; 
  99.  
  100. /** This filter is documented in wp-includes/general-template.php */ 
  101. $page_links[] = "<a class='page-numbers' href='" . esc_url( apply_filters( 'paginate_links', $link ) ) . "'>" . $args['before_page_number'] . number_format_i18n( $n ) . $args['after_page_number'] . "</a>"; 
  102. $dots = true; 
  103. elseif ( $dots && ! $args['show_all'] ) : 
  104. $page_links[] = '<span class="page-numbers dots">' . __( '…' ) . '</span>'; 
  105. $dots = false; 
  106. endif; 
  107. endif; 
  108. endfor; 
  109. if ( $args['prev_next'] && $current && $current < $total ) : 
  110. $link = str_replace( '%_%', $args['format'], $args['base'] ); 
  111. $link = str_replace( '%#%', $current + 1, $link ); 
  112. if ( $add_args ) 
  113. $link = add_query_arg( $add_args, $link ); 
  114. $link .= $args['add_fragment']; 
  115.  
  116. /** This filter is documented in wp-includes/general-template.php */ 
  117. $page_links[] = '<a class="next page-numbers" href="' . esc_url( apply_filters( 'paginate_links', $link ) ) . '">' . $args['next_text'] . '</a>'; 
  118. endif; 
  119. switch ( $args['type'] ) { 
  120. case 'array' : 
  121. return $page_links; 
  122.  
  123. case 'list' : 
  124. $r .= "<ul class='page-numbers'>\n\t<li>"; 
  125. $r .= join("</li>\n\t<li>", $page_links); 
  126. $r .= "</li>\n</ul>\n"; 
  127. break; 
  128.  
  129. default : 
  130. $r = join("\n", $page_links); 
  131. break; 
  132. return $r;