paginate_links() │ WP 2.1.0

Чтобы добавить пагинацию на страницу результатов поиска или страницу архивов, используйте такой код:

function my_pagenavi() {
	global $wp_query;

	$big = 999999999; // уникальное число для замены

	$args = array(
		'base'    => str_replace( $big, '%#%', get_pagenum_link( $big ) ),
		'format'  => '',
		'current' => max( 1, get_query_var('paged') ),
		'total'   => $wp_query->max_num_pages,
	);

	$result = paginate_links( $args );

	// удаляем добавку к пагинации для первой страницы
	$result = preg_replace( '~/page/1/?([\'"])~', '', $result );

	echo $result;
}

// Теперь, где нужно вывести пагинацию используем
// my_pagenavi();

В примере ниже будем выводить продукты WooCommerce (post_type=product) на отдельной странице записи (post_type=post). Т.е. будем использовать произвольный запрос и сделаем для него пагинацию.

// Запрашиваем продукты
$query = new WP_Query( [
	'post_type'      => 'product',
	'posts_per_page' => 5,
	'paged'          => get_query_var( 'page' ),
] );

// Обрабатываем полученные в запросе продукты, если они есть
if ( $query->have_posts() ) {

	while ( $query->have_posts() ) {
		$query->the_post();

		// выводим заголовок
		the_title();
	}

	wp_reset_postdata();
}

// Выводим пагинацию, если продуктов больше запрошенного количество
echo paginate_links( [
	'base'    => user_trailingslashit( wp_normalize_path( get_permalink() .'/%#%/' ) ),
	'current' => max( 1, get_query_var( 'page' ) ),
	'total'   => $query->max_num_pages,
] );

Мы указали выводить по 5 товаров, если их, к примеру 22, то будет выведено 5 элементов пагинации, из которых 4 будут ссылками следующего вида:

Текущая страница, ссылка не выводится (5 продуктов)
http://example.com/название-записи/2/ (5 продуктов)
http://example.com/название-записи/3/ (5 продуктов)
http://example.com/название-записи/4/ (5 продуктов)
http://example.com/название-записи/5/ (2 продукта)

Обратите внимание:

• В параметре base где формируется вид ссылки пагинации не используются такие слова как page или paged. Потому что c page будет перенаправление со страницы пагинации на саму запись, а с paged будет 404 ошибка на странице пагинации.

• Для получения номера страницы пагинации вместо привычного get_query_var( 'paged' ) используем get_query_var( 'page' ).

• Этот код не будет работать на страницах у которых контент делиться на несколько страниц тегом <!--nextpage-->, подробнее см. здесь.

paginate_links() всегда возвращает HTML, даже если параметр type=array вы получите массив готовых <a> тегов. Это может не подойти когда нужно полностью изменить HTML-структуру вашей пагинации. Ниже небольшая функция, которая возвращает массив объектов вместо HTML.

/**
 * Generates array of pagination links.
 *
 * @author Kama (wp-kama.com)
 * @varsion 2.5
 *
 * @param array $args {
 *
 *     @type int    $total        Maximum allowable pagination page.
 *     @type int    $current      Current page number.
 *     @type string $url_base     URL pattern. Use `{pagenum}` placeholder.
 *     @type string $first_url    URL to first page. Default: '' - taken automaticcaly from $url_base.
 *     @type int    $mid_size     Number of links before/after current: 1 ... 1 2 [3] 4 5 ... 99. Default: 2.
 *     @type int    $end_size     Number of links at the edges: 1 2 ... 3 4 [5] 6 7 ... 98 99. Default: 1.
 *     @type bool   $show_all     true - Show all links. Default: false.
 *     @type string $a_text_patt  `%s` will be replaced with number of pagination page. Default: `'%s'`.
 *     @type bool   $is_prev_next Whether to show prev/next links. « Previou 1 2 [3] 4 ... 99 Next ». Default: false.
 *     @type string $prev_text    Default: `« Previous`.
 *     @type string $next_text    Default: `Next »`.
 * }
 *
 * @return array
 */
function kama_paginate_links_data( array $args ): array {
	global $wp_query;

	$args += [
		'total'        => 1,
		'current'      => 0,
		'url_base'     => '/{pagenum}',
		'first_url'    => '',
		'mid_size'     => 2,
		'end_size'     => 1,
		'show_all'     => false,
		'a_text_patt'  => '%s',
		'is_prev_next' => false,
		'prev_text'    => '« Previous',
		'next_text'    => 'Next »',
	];

	$rg = (object) $args;

	$total_pages = max( 1, (int) ( $rg->total ?: $wp_query->max_num_pages ) );

	if( $total_pages === 1 ){
		return [];
	}

	// fix working parameters

	$rg->total = $total_pages;
	$rg->current = max( 1, abs( $rg->current ?: get_query_var( 'paged', 1 ) ) );

	$rg->url_base = $rg->url_base ?: str_replace( PHP_INT_MAX, '{pagenum}', get_pagenum_link( PHP_INT_MAX ) );
	$rg->url_base = wp_normalize_path( $rg->url_base );

	if( ! $rg->first_url ){
		// /foo/page(d)/2 >>> /foo/ /foo?page(d)=2 >>> /foo/
		$rg->first_url = preg_replace( '~/paged?/{pagenum}/?|[?]paged?={pagenum}|/{pagenum}/?~', '', $rg->url_base );
		$rg->first_url = user_trailingslashit( $rg->first_url );
	}

	// core array

	if( $rg->show_all ){
		$active_nums = range( 1, $rg->total );
	}
	else {

		if( $rg->end_size > 1 ){
			$start_nums = range( 1, $rg->end_size );
			$end_nums = range( $rg->total - ($rg->end_size - 1), $rg->total );
		}
		else {
			$start_nums = [ 1 ];
			$end_nums = [ $rg->total ];
		}

		$from = $rg->current - $rg->mid_size;
		$to = $rg->current + $rg->mid_size;

		if( $from < 1 ){
			$to = min( $rg->total, $to + absint( $from ) );
			$from = 1;

		}
		if( $to > $rg->total ){
			$from = max( 1, $from - ($to - $rg->total) );
			$to = $rg->total;
		}

		$active_nums = array_merge( $start_nums, range( $from, $to ), $end_nums );
		$active_nums = array_unique( $active_nums );
		$active_nums = array_values( $active_nums ); // reset keys
	}

	// fill by core array

	$pages = [];

	if( 1 === count( $active_nums ) ){
		return $pages;
	}

	$item_data = static function( $num ) use ( $rg ){

		$data = [
			'is_current'   => false,
			'page_num'     => null,
			'url'          => null,
			'link_text'    => null,
			'is_prev_next' => false,
			'is_dots'      => false,
		];

		if( 'dots' === $num ){

			return (object) ( [
			   'is_dots' => true,
			   'link_text' => '…',
			] + $data );
		}

		$is_prev = 'prev' === $num && ( $num = max( 1, $rg->current - 1 ) );
		$is_next = 'next' === $num && ( $num = min( $rg->total, $rg->current + 1 ) );

		$data = [
			'is_current'   => ! ( $is_prev || $is_next ) && $num === $rg->current,
			'page_num'     => $num,
			'url'          => 1 === $num ? $rg->first_url : str_replace( '{pagenum}', $num, $rg->url_base ),
			'is_prev_next' => $is_prev || $is_next,
		] + $data;

		if( $is_prev ){
			$data['link_text'] = $rg->prev_text;
		}
		elseif( $is_next ) {
			$data['link_text'] = $rg->next_text;
		}
		else {
			$data['link_text'] = sprintf( $rg->a_text_patt, $num );
		}

		return (object) $data;
	};

	foreach( $active_nums as $indx => $num ){

		$pages[] = $item_data( $num );

		// set dots
		$next = $active_nums[ $indx + 1 ] ?? null;
		if( $next && ($num + 1) !== $next ){
			$pages[] = $item_data( 'dots' );
		}
	}

	if( $rg->is_prev_next ){
		$rg->current !== 1 && array_unshift( $pages, $item_data( 'prev' ) );
		$rg->current !== $rg->total && $pages[] = $item_data( 'next' );
	}

	return $pages;
}

Что выводит функция:

$links_data = kama_paginate_links_data( [
	'total'    => 3,
	'current'  => 2,
	'url_base' => 'http://site.com/page-name/paged/{pagenum}',
	'mid_size' => 2,
] );

print_r( $links_data );

/*
Array
(
	[0] => stdClass Object
		(
			[is_current] => 
			[page_num] => 288
			[url] => https://holder.loc/ru/coins/page/288
			[is_prev_next] => 1
			[link_text] => « Previous
			[is_dots] => 
		)

	[1] => stdClass Object
		(
			[is_current] => 
			[page_num] => 1
			[url] => https://holder.loc/ru/coins/
			[is_prev_next] => 
			[link_text] => 1
			[is_dots] => 
		)

	[2] => stdClass Object
		(
			[is_dots] => 1
			[link_text] => …
			[is_current] => 
			[page_num] => 
			[url] => 
			[is_prev_next] => 
		)

	[3] => stdClass Object
		(
			[is_current] => 
			[page_num] => 285
			[url] => https://holder.loc/ru/coins/page/285
			[is_prev_next] => 
			[link_text] => 285
			[is_dots] => 
		)

	[4] => stdClass Object
		(
			[is_current] => 
			[page_num] => 286
			[url] => https://holder.loc/ru/coins/page/286
			[is_prev_next] => 
			[link_text] => 286
			[is_dots] => 
		)

	[5] => stdClass Object
		(
			[is_current] => 1
			[page_num] => 287
			[url] => https://holder.loc/ru/coins/page/287
			[is_prev_next] => 
			[link_text] => 287
			[is_dots] => 
		)

)
*/

Теперь используем эту функцию в цикле:

<?php

$links_data = kama_paginate_links_data( [
	'total' => 3,
	'current' => 2,
	'url_base' => 'http://site.com/page-name/paged/{pagenum}',
] );

if( $links_data ){
	?>

	<ul>
		<?php foreach( $links_data as $link ) { ?>
		<li>
			<?php if ( $link->is_dots ) { ?>
				<span><?= $link->link_text ?></span>
			<?php } elseif ( $link->is_current ) { ?>
				<strong><?= $link->link_text ?></strong>
			<?php } else { ?>
				<a href="<?php esc_attr_e( $link->url ) ?>"><?php _e( $link->link_text ) ?></a>
			<?php } ?>
		</li>
		<?php } ?>
	</ul>

	<?php
}

Получим:

<ul>
	<li>
		<a href="http://site.com/page-name/paged/1">1</a>
	</li>
	<li>
		<strong>2</strong>
	</li>
	<li>
		<a href="http://site.com/page-name/paged/3">3</a>
	</li>
</ul>

Когда записи выводятся отдельным запросом с помощью new WP_Query для вывода пагинации можно установить параметр total, в котором указать свойство WP_Query::$max_num_pages. Рассмотрим пример:

Это лишь демонстрационный пример, потому что он не учитывает основной запрос, в котором может получаться 404 страница и до этого кода дело вообще не дойдет. Также он может работать неправильно на отдельной странице записи.

<?php
// 1 значение по умолчанию
$paged = get_query_var( 'paged' ) ? absint( get_query_var( 'paged' ) ) : 1;

$the_query = new WP_Query( array(
	'posts_per_page' => 5,
	'category_name'  => 'gallery',
	'paged'          => $paged,
) );

// цикл вывода полученных записей
while( $the_query->have_posts() ){
	$the_query->the_post();
	?>
	<!-- HTML каждой записи -->
	<?php
}
wp_reset_postdata();

// пагинация для произвольного запроса
$big = 999999999; // уникальное число

echo paginate_links( array(
	'base'    => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'current' => max( 1, get_query_var('paged') ),
	'total'   => $the_query->max_num_pages
) );
?>

Допустим мы изменили шаблон навигации через хук navigation_markup_template и теперь мы ходим чтобы все вложенные элементы соответствовали БЭМ классам.

Класс БЭМ блока у нас hlpagination:

<?php
/// изменим шаблон навигации (пагинации)
add_filter( 'navigation_markup_template', 'hl_navigation_template', 10, 2 );

function hl_navigation_template( $template, $class ){

	ob_start();
	?>
	<nav class="hlpagination %1$s" role="navigation">
		<div class="hlpagination__nav-links">%3$s</div>
	</nav>
	<?php
	return ob_get_clean();
}

%3$s заменяется на то что возвращает paginate_links() и у нее всем классам также нужно добавить префикс:

/// поправим html пагинации для функции paginate_links()
add_filter( 'paginate_links_output', 'hl_fix_paginate_links' );

function hl_fix_paginate_links( $html ){

	$html = preg_replace_callback( '/ class=[\'"][^\'"]+[\'"]/', static function( $mm ){

		return strtr( $mm[0], [
			'current'      => '--current',
			'prev'         => 'hlpagination__prev',
			'next'         => 'hlpagination__next',
			'dots'         => 'hlpagination__dots',
			'page-numbers' => 'hlpagination__numbers',
		] );

	}, $html );

	return $html;
}