Displaying Highlighted Search Terms

As the content of a WordPress site grows (using this site as my case study) search results will also grow. Typically on a WordPress site the search results will either show the post content, the excerpt, or a limited version of the content. WordPress does not highlight the words in the content which match the search terms, nor does it automatically display the relevant sections of a post’s content when using the excerpt or a limited version of content. This can lead to potentially unintuitive search results which require your readers to open every result and scan for matches on their own.

Unique Challenges

WordPress search matches both full sentences and single words, we wish to highlight each separately.
The matched search terms may appear anywhere in the content.
The matched search terms may appear more than once in our post.
We are limiting the length of content in our results to 500.
The matched search terms may appear only in the post title.

Challenge #1: WordPress search matches both full sentences and single words, we wish to highlight each separately.

The first thing we need to know is the text that was searched for, both the terms as separated by WordPress and the full search. We can retrieve both with built in functions.

PHP

Challenge #2: The matched search terms may appear anywhere in the content.

For this challenge, we need to build an array of string positions in our content where each search term resides. We also want to favor full search matches over single term matches so we don’t double up.

PHP

Challenge #3: The matched search terms may appear more than once in our post.

Here is where things get interesting. We need to know the string positions of all matches in our content, while maintaining our logic that full search matches don’t double up on single term matches.

PHP

Challenge #4: We are limiting the length of content in our results to 500.

We now have the positions of all our matches within the full content, but we don’t want to display the full content in our search results. Instead we only want to display the paragraphs that have matching search terms.

Our code is getting to be a bit verbose now so let’s create a simple class and split our logic into clean methods.

PHP

<?php
class Search {

public function get_content_highlight_matches() {
		$content = wpautop( get_the_content() );
		$paragraphs = explode( '', $content );
		$highlighted = '';
		foreach ( $paragraphs as $p ) {
			if ( '' === $p || '' === $p ) {
				continue;
			}
			$p = strip_tags( strip_shortcodes( $p ) );
			$p = '' . $p . ''; // Put tag back on the paragraph.
			$positions = $this->get_positions_of_search_matches( $p );
			if ( ! empty( $positions ) ) {
				$highlighted .= $this->highlight_search_matches( $p, $positions );
			}
		}

return $highlighted;
	}

private function highlight_search_matches( $content, $positions ) {
		$full_search = get_search_query();
		$original_length = strlen( $content );
		foreach ( $positions as $_string_position => $_match ) {
			$class            = 'partial-match';
			// Account for the additional string length from the added spans.
			$_string_position += strlen( $content ) – $original_length;
			if ( strlen( $_match ) === strlen( $full_search ) ) {
				$class = 'full-match';
			}

$content = substr_replace( $content, '', $_string_position + strlen( $_match ), 0 );
			$content = substr_replace( $content, "", $_string_position, 0 );
		}

return $content;
	}

private function get_positions_of_search_matches( $content ) {
		$full_search = get_search_query();
		$position    = -1;
		$string_positions = [];
		foreach ( get_query_var( 'search_terms' ) as $i => $_term ) {
			while ( ( $position = strpos( $content, $_term, $position + 1 ) ) !== false ) {
				// If we don't already have a full_search match containing this string.
				if ( ! array_key_exists( $position – strpos( $full_search, $_term ), $string_positions ) ) {
					$string_positions[ $position ] = $_term;
				}

// If we have a full_search match starting with this string.
				if ( 0 === $i && substr( $content, $position, \strlen( $full_search ) ) === $full_search ) {
					$string_positions[ $position ] = $full_search;
				}
			}
		}
        ksort( $string_positions );
        
		return $string_positions;
	}
}

Challenge #5: The matched search terms may appear only in the post title.

There are situations where search results will match a title of a post. This post does not necessarily contain the search terms anywhere within the content. In those situations we don’t want a blank content area so instead we return the post excerpt.

We do this by editing the get_content_highlight_matches method slightly.

PHP

Putting It all Together.

We have the functionality, now lets add it to our theme. In our search.php template we replace any calls to the_content with a call to our class.

PHP

Or we could create a simple template tag which keeps our templates cleaner looking.

PHP

Great! Now our search results are only displaying the paragraphs which contain matches and are greatly more intuitive.

But wait…. We have these cool little  tags available to highlight the matches within the results. Let’s add some style to them.

CSS