WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get the excerpt

Description

Returns the excerpt of the post. This is either a user-supplied excerpt, that is returned unchanged, or an automatically generated word-counted trimmed-down version of the full post content.

The auto-generated excerpts have all shortcodes and tags removed which means it is just an unformatted string that would not see any line-breaks in any form of output, since the actual line-breaks in the raw text are also removed.

When called through the_excerpt() this implies that the auto-gen excerpts are just raw text with <p></p> tags wrapped around it, basically.

Auto-gen excerpts have a "more" tag appended to them. This tag is '[…]' by default. It can be changed through the excerpt_more filter.

The default word length is 55 words. It can be changed through the excerpt_length filter.

Usage

 <?php $excerpt get_the_excerpt$deprecated ?> 

This function must be used within The Loop.

Parameters

$deprecated is not required.

Return Values

  • Returns an existing excerpt unchanged (by default) but applies get_the_excerpt filters to it.
  • Returns a trimmed-down version of the full post content as described, additionally applying wp_trim_excerpt filters to it. 'wp_trim_excerpt' is chained from 'get_the_excerpt', meaning that your own get_the_excerpt filter will get called before or after the trim depending on the priority of your filter. If called before, your $text parameter will be an empty string if there is no user supplied excerpt, whereas it will be the trimmed-down version of the full post if called after. In the latter case it might be useful or more meaningful to use 'wp_trim_excerpt' since it has a second parameter giving you the untrimmed input to the wp_trim_excerpt function, meaning this second parameter is simply the raw $post->post_excerpt.
  • For password protected pages it returns a string, which has a default value of "There is no excerpt because this is a protected post." This text can be changed in the function definition.

Examples

get_the_excerpt() can be used to retrieve and store the value in a variable, without outputting it to the page.

<?php
$my_excerpt = get_the_excerpt();
if ( $my_excerpt != '' ) {
	// Some string manipulation performed
}
echo $my_excerpt; // Outputs the processed value to the page
?>

Use get_the_excerpt() to print an excerpt by specifying a maximium number of characters.

<?php
the_excerpt_max_charlength(140);

function the_excerpt_max_charlength($charlength) {
	$excerpt = get_the_excerpt();
	$charlength++;

	if ( mb_strlen( $excerpt ) > $charlength ) {
		$subex = mb_substr( $excerpt, 0, $charlength - 5 );
		$exwords = explode( ' ', $subex );
		$excut = - ( mb_strlen( $exwords[ count( $exwords ) - 1 ] ) );
		if ( $excut < 0 ) {
			echo mb_substr( $subex, 0, $excut );
		} else {
			echo $subex;
		}
		echo '[...]';
	} else {
		echo $excerpt;
	}
}
?>


Change Log

Since: 0.71

Source File

get_the_excerpt() is located in wp-includes/post-template.php.

Related

the_excerpt()

See also index of Function Reference and index of Template Tags.