get_the_excerpt │ хук-фильтр │ WP 1.2.0

Позволяет изменить отрывок записи, получаемый через get_the_excerpt().

Фильтр применяется к значению поля post_excerpt перед возвратом результата. Изменения не сохраняются в БД. Он также влияет на the_excerpt(), которая получает текст через get_the_excerpt().

По умолчанию к хуку подключена wp_trim_excerpt() с приоритетом 10. Если переданный текст пуст (после удаления пробелов по краям), она создаёт отрывок из контента записи. Обычно это первые 55 слов без HTML, с окончанием […]. Длину и окончание меняют фильтры excerpt_length и excerpt_more. Непустой отрывок, заданный вручную, автоматически не сокращается.

Выбирайте приоритет обработчика по задаче:

• Меньше 10: изменить исходный текст до автоматического создания отрывка. Если вернуть непустую строку, стандартная генерация из содержимого не выполнится.
• Больше 10: изменить результат после стандартной обработки.

Использование

add_filter( 'get_the_excerpt', 'wp_kama_get_the_excerpt_filter', 10, 2 );

/**
 * Function for `get_the_excerpt` filter-hook.
 * 
 * @param string  $post_excerpt The post excerpt.
 * @param WP_Post $post         Post object.
 *
 * @return string
 */
function wp_kama_get_the_excerpt_filter( $post_excerpt, $post ){
	// filter...
	return $post_excerpt;
}

$post_excerpt(строка)

Фильтруемый отрывок.
Изначально это значение $post->post_excerpt, которое может быть пустым.
К моменту вызова обработчика текст уже могли изменить предыдущие фильтры, включая wp_trim_excerpt().

$post(WP_Post)

Объект записи, для которой получают отрывок.
Используйте этот объект вместо глобальной $post: отрывок могут получать для другой записи.

Примеры

#1 Добавим ссылку «Читать далее» к отрывку

Пример действует только для записей типа post с заполненным полем отрывка. Проверка has_excerpt() отличает ручной отрывок от автоматически созданного.

add_filter( 'get_the_excerpt', 'mytheme_excerpt_read_more', 20, 2 );

function mytheme_excerpt_read_more( $excerpt, $post ) {

	if ( 'post' !== $post->post_type || ! has_excerpt( $post ) ) {
		return $excerpt;
	}

	return $excerpt . sprintf( <a href="%s">%s</a>',
		esc_url( get_permalink( $post ) ),
		esc_html__( 'Читать далее', 'mytheme' )
	);
}

#2 Ограничим длину отрывка

Фильтр excerpt_length сам по себе не сокращает отрывок. Здесь явно применим длину и окончание через wp_trim_words(). Также удалит HTML-теги.

add_filter( 'get_the_excerpt', 'mytheme_trim_manual_excerpt', 20, 2 );

function mytheme_trim_manual_excerpt( $excerpt, $post ) {

	if ( 'post' !== $post->post_type || ! has_excerpt( $post ) ) {
		return $excerpt;
	}

	$length = (int) apply_filters( 'excerpt_length', (int) _x( '55', 'excerpt_length' ) );
	$more   = apply_filters( 'excerpt_more', ' […]' );

	return wp_trim_words( $excerpt, $length, $more );
}

apply_filters( 'get_the_excerpt', $text, $post )

#3 Заменим пустой результат текстом-заглушкой

Приоритет 20 позволяет сначала выполнить стандартную генерацию. Заглушка появится, только если результат всё ещё пуст. Если нужна заглушка вместо генерации из содержимого, используйте приоритет 5.

add_filter( 'get_the_excerpt', 'mytheme_excerpt_fallback', 20, 2 );

function mytheme_excerpt_fallback( $excerpt, $post ) {

	if ( 'post' === $post->post_type && '' === trim( $excerpt ) ) {
		return __( 'Откройте запись, чтобы прочитать материал.', 'mytheme' );
	}

	return $excerpt;
}