Highlighting & snippets

TNTSearch includes built-in support for highlighting matched search terms in text and extracting relevant snippets from longer documents. These features help users quickly identify why a result matched their query.

Highlighting

The highlight() method wraps matching terms in an HTML tag:

$tnt = new TNTSearch;
$tnt->loadConfig($config);
$tnt->selectIndex('articles.index');

$text = "This is some text about Romeo and Juliet";
$output = $tnt->highlight($text, 'romeo juliet', 'em');
// "This is some text about <em>Romeo</em> and <em>Juliet</em>"

Parameters

$tnt->highlight($text, $needle, $tag = 'em', $options = []);

Parameter	Description
`$text`	The text to highlight
`$needle`	The search terms to highlight (space-separated)
`$tag`	HTML tag to wrap matches in (default: `em`)
`$options`	Array of options (see below)

Options

Option	Default	Description
`wholeWord`	`true`	Only match whole words, not partial matches
`caseSensitive`	`false`	Whether matching is case-sensitive
`stripLinks`	`false`	Strip `<a>` tags around matching text
`tagOptions`	`[]`	HTML attributes to add to the highlight tag

Examples

$hl = new \TeamTNT\TNTSearch\Support\Highlighter;

// Whole word matching (default)
$hl->highlight("This is some text", "is text", 'em', ['wholeWord' => true]);
// "This <em>is</em> some <em>text</em>"

// Partial matching
$hl->highlight("This is some text", "is text", 'em', ['wholeWord' => false]);
// "Th<em>is</em> <em>is</em> some <em>text</em>"

// Case sensitive
$hl->highlight("This is some text", "this text", 'em', ['caseSensitive' => true]);
// "This is some <em>text</em>"

// Custom tag
$hl->highlight("This is some text", "text", 'b');
// "This is some <b>text</b>"

// With tag attributes
$hl->highlight($text, "romeo", 'span', [
    'tagOptions' => [
        'class' => 'search-highlight',
        'data-toggle' => 'tooltip',
    ]
]);
// "<span class="search-highlight" data-toggle="tooltip">Romeo</span>"

Extracting snippets

For long documents, you typically want to show a relevant portion of the text rather than the entire document. The snippet() method extracts the most relevant passage containing the search terms:

$tnt = new TNTSearch;
$tnt->loadConfig($config);
$tnt->selectIndex('articles.index');

$snippet = $tnt->snippet(
    'search terms',    // the search query
    $fullArticleText,  // the full document text
    300,               // max length of the snippet
    50,                // number of characters to include before the match
    '...'              // indicator for truncation
);

Parameters

$tnt->snippet($words, $fulltext, $rellength = 300, $prevcount = 50, $indicator = '...');

Parameter	Default	Description
`$words`	-	The search terms
`$fulltext`	-	The full document text
`$rellength`	`300`	Maximum length of the extracted snippet
`$prevcount`	`50`	Characters to include before the first match
`$indicator`	`'...'`	String appended/prepended when text is truncated

Example

$fulltext = "Lorem ipsum dolor sit amet... [very long text] ...
This is a sentence that contains the phrase This is some text and
thats it... [more long text]";

$snippet = $tnt->snippet('This is some text', $fulltext, 100);
// "...bla This is a sentence that contains the phrase This is some text and thats it bla bla bla bla..."

The snippet method finds the most relevant portion of the document where search terms appear closest together.

Combining highlighting and snippets

For the best search results display, combine both features:

$tnt->selectIndex('articles.index');
$results = $tnt->search('romeo juliet');

foreach ($results['ids'] as $id) {
    $article = getArticleById($id); // your database query

    // Extract relevant snippet
    $snippet = $tnt->snippet('romeo juliet', $article->body, 200);

    // Highlight matches in the snippet
    $highlighted = $tnt->highlight($snippet, 'romeo juliet');

    echo "<p>$highlighted</p>";
}