wp_trim_words( string $text, int $num_words = 55, string $more = null )

Trims text to a certain number of words.


Description Description

This function is localized. For languages that count ‘words’ by the individual character (such as East Asian languages), the $num_words argument will apply to the number of individual characters.


Parameters Parameters

$text

(string) (Required) Text to trim.

$num_words

(int) (Optional) Number of words.

Default value: 55

$more

(string) (Optional) What to append if $text needs to be trimmed. Default '…'.

Default value: null


Top ↑

Return Return

(string) Trimmed text.


Top ↑

Source Source

File: wp-includes/formatting.php

function wp_trim_words( $text, $num_words = 55, $more = null ) {
	if ( null === $more ) {
		$more = __( '…' );
	}

	$original_text = $text;
	$text          = wp_strip_all_tags( $text );
	$num_words     = (int) $num_words;

	/*
	 * translators: If your word count is based on single characters (e.g. East Asian characters),
	 * enter 'characters_excluding_spaces' or 'characters_including_spaces'. Otherwise, enter 'words'.
	 * Do not translate into your own language.
	 */
	if ( strpos( _x( 'words', 'Word count type. Do not translate!' ), 'characters' ) === 0 && preg_match( '/^utf\-?8$/i', get_option( 'blog_charset' ) ) ) {
		$text = trim( preg_replace( "/[\n\r\t ]+/", ' ', $text ), ' ' );
		preg_match_all( '/./u', $text, $words_array );
		$words_array = array_slice( $words_array[0], 0, $num_words + 1 );
		$sep         = '';
	} else {
		$words_array = preg_split( "/[\n\r\t ]+/", $text, $num_words + 1, PREG_SPLIT_NO_EMPTY );
		$sep         = ' ';
	}

	if ( count( $words_array ) > $num_words ) {
		array_pop( $words_array );
		$text = implode( $sep, $words_array );
		$text = $text . $more;
	} else {
		$text = implode( $sep, $words_array );
	}

	/**
	 * Filters the text content after words have been trimmed.
	 *
	 * @since 3.3.0
	 *
	 * @param string $text          The trimmed text.
	 * @param int    $num_words     The number of words to trim the text to. Default 55.
	 * @param string $more          An optional string to append to the end of the trimmed text, e.g. ….
	 * @param string $original_text The text before it was trimmed.
	 */
	return apply_filters( 'wp_trim_words', $text, $num_words, $more, $original_text );
}

Top ↑

Changelog Changelog

Changelog
Version Description
3.3.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 4 content
    Contributed by Jb Audras

    Example: display comment excerpt in a comments custom query.

    $args = array(
    	'number' => 3,
    );
    $comments_query = new WP_Comment_Query;
    $comments = $comments_query->query( $args );
    if ( $comments ) {
    	foreach ( $comments as $comment ) {
    		echo wp_trim_words( $comment->comment_content, 20, ' […]' );
    	}
    }
    

You must log in before being able to contribute a note or feedback.