Relevanssi has lots of filter hooks you can use to modify how the plugin behaves. Most of these are pretty advanced and an average user probably doesn’t have to worry about them, but if you’re going to do something more demanding, knowledge of these filters will help.

If you do something that would be made easier by a new filter, please let me know – I do like adding new filter hooks, as that is a very easy way to add flexibility to the plugin with little effort.

relevanssi_admin_search_ok (true, $query)
This filter can modify whether the default admin search query by WP is blocked or not.

relevanssi_bots_to_not_log ($bots_array)
This filter can be used to prevents bots from being logged in the user searches blog. This filter expects an array with key => value pairs where key is the name of the bot and value the user agent of the bot.

relevanssi_content_to_index (”, $post)
You can use this filter to add extra content to posts before Relevanssi indexes them. The additional content is then trimmed and a space is added between the old content and the added content.

relevanssi_default_tax_query_relation (‘OR’)
By default, Relevanssi assumes the taxonomy query relation is OR. If you want to change the default relation to AND, you can use this filter hook to do so.

relevanssi_df_query_filter ($query)
Relevanssi calculates DF (document frequency) with a simple MySQL query. You can filter that query with this hook. Mostly useful if you modify the way fuzzy queries are done, in which case you’ll want to make the change to this query as well.

relevanssi_do_not_index (false, $post->ID)
If this filter returns true, Relevanssi will not index this post. You can use this filter to selectively prevent posts from being indexed.

relevanssi_ellipsis (“…”)
If you want to replace the … in the end and beginning of excerpts with something else, use this filter.

relevanssi_excerpt_content ($content, $post, $query)
When Relevanssi builds excerpts, the post content passes through this filter, after it goes through relevanssi_pre_excerpt_content and the_content. All these filters give you a chance to add more content to the post to work as a building block of excerpts. For example, if you want custom field content to appear in the excerpts in case the search term is found in a custom field, use this filter or relevanssi_pre_excerpt_content to simply concatenate the custom field content to the end of the post content – the excerpt building algorithm will find it there.

relevanssi_fuzzy_query (“(term LIKE ‘%#term#’ OR term LIKE ‘#term#%’) “)
This filter lets you modify the way Relevanssi runs the fuzzy queries. The main thing you can do here is to change this value to “(term LIKE ‘%#term#%’) ” to make it match search term completely inside words. By default the search term in fuzzy search must match either beginning or the end of a word. #term# will be replaced by the actual search term later.

relevanssi_get_words_query ($query) (Premium only)
Relevanssi Premium uses a “Did you mean” function that needs to know all the words in your database. This, however, can be problematic once your search index grows large enough. To fix that, you need to prune out the words that appear only once to make the amount of data smaller. This can be done using this hook. See “Did you mean” suggestions, the solution is in the end of the article.

relevanssi_hits_filter (array($hits, $query))
This is one of the most powerful filters in Relevanssi. It lets you modify the array $hits, which contains all the hits Relevanssi found. The hits are post objects, which makes manipulating them easy. At this point, you can reorder the search results at will, remove them, add new and so on. The parameter array also contains the search query, which Relevanssi doesn’t need back, it’s just there for reference in case you need it. Remember to return the array of posts like this: array($hits).

Relevanssi filter functions on this hook:
- relevanssi_wpml_filter() (default priority) adds WPML language support

relevanssi_index_comments_exclude (false, $post_id)
If this filter returns true, Relevanssi won’t index the comments for the $post_id mentioned in the second parameter.

relevanssi_index_content (true)
If this filter returns false, Relevanssi won’t index content of posts or pages.

relevanssi_index_custom_fields ($custom_fields)
The filter is given a list of custom fields before the custom fields are indexed. Feel free to manipulate the list as you wish. This can be useful for selecting the indexed custom fields with a regexp, for example.

relevanssi_index_titles (true)
If this filter returns false, Relevanssi won’t index titles of posts or pages.

relevanssi_match ($match, $idf)
Another powerful filter. This lets you modify the $match objects, which are used to calculate the weight of the documents. The object has attributes which contain the number of hits in different categories. Post ID is $match->doc, term frequency (TF) is $match->tf and the total weight is in $match->weight. The filter is also passed $idf, which is the inverse document frequency (IDF). The weight is calculated as TF * IDF, which means you may need the IDF, if you wish to recalculate the weight for some reason.

relevanssi_modify_wp_query ($wp_query)
If you want to make some changes in the query before Relevanssi sees it, you can use this filter hook to modify the $wp_query variable before it is passed to Relevanssi. This is a good place, for example, to combine query variables. You can for example have one input field for positive search terms and another for negative search terms and then use this filter to combine them both into the ‘s’ query variable where Relevanssi will look for the search terms.

relevanssi_options_capability (‘manage_options’)
This filter can be changed to adjust the default capability required to see Relevanssi settings. The default value is ‘manage_options’.

relevanssi_post_ok ($post_ok, $post_ID)
Can this post be included in the search results? This is the hook you’ll use if you want to add support for a membership plugin, for example. Based on the post ID, your function needs to return true or false.

Relevanssi filter function on this hook:
- relevanssi_default_post_ok (priority: 9) contains the default logic. If you want to override this, either remove this function from the hook (and make sure you cover the cases for private posts or drafts, see the default function for more details) or run yours after this on a lower priority.

relevanssi_pre_excerpt_content ($post->post_content, $post, $query)
When Relevanssi builds excerpts, the post content passes first through this filter. Then it’s passed to the_content, then relevanssi_excerpt_content. All these filters give you a chance to add more content to the post to work as a building block of excerpts. For example, if you want custom field content to appear in the excerpts in case the search term is found in a custom field, use this filter or relevanssi_excerpt_content to simply concatenate the custom field content to the end of the post content – the excerpt building algorithm will find it there.

relevanssi_pre_indexing_query
This is an action hook that runs before the main indexing query. This is a fairly large query and can go over the MAX_JOIN_SIZE set on the server. If that is the case, you can use this action hook to run “SET OPTION SQL_BIG_SELECTS=1″ on the MySQL server to allow the large join.

relevanssi_query_filter ($query)
This is your final chance to modify the main Relevanssi query before it is run on the database. This is also useful for echoing out the query when doing debugging.

Relevanssi filter function on this hook:
- relevanssi_limit_filter() (default priority) adds the LIMIT parameter

relevanssi_premium_tokenizer ($token) (Premium only)
This hook is used to enable the stemmer in Premium. This filter sees every token (word) as it comes through the tokenizer, so you can use it for something else as well.

Relevanssi filter function on this hook:
- relevanssi_enable_stemmer (default priority, by default does nothing)

relevanssi_remove_punctuation
Relevanssi uses a hooked function to remove punctuation from search queries and documents. Some punctuation is replaced with spaces, some simply removed. If you’re interested in how this works, take a closer look at relevanssi_remove_punct() function in lib/common.php. If you want to change some of the behaviour, just unhook the default function and replace it with your own.

Relevanssi filter function on this hook:
relevanssi_remove_punct (default priority)

relevanssi_results ($results)
This filter lets you modify an array that contains (post_ID => weight) pairs. If unmodified, Relevanssi will fetch these posts and return them as the final search results (to another Relevanssi function, which will then take a slice of the array, as determined by how many posts are shown per page and which page of search results the user wants).

relevanssi_search_filters ($array)
This filter lets you manipulate search parameters before Relevanssi uses them. The array contains following keys: ‘q’, ‘cat’, ‘excat’, ‘tag’, ‘expost’, ‘post_type’, ‘taxonomy’, ‘taxonomy_term’, ‘operator’, ‘search_blogs’, ‘customfield_key’, ‘customfield_value’, ‘author’.

relevanssi_search_ok ($search_ok)
Relevanssi is activated always when posts are requested. Thus, Relevanssi needs to figure out if it’s an actual search, before taking action. If is_search() is true, it’s a search. If is_admin() is true, then Relevanssi will reconsider and so on. You can modify this behaviour with this hook, which is fired after Relevanssi has checked other cases. By returning a true here, you’ll force Relevanssi to become active. This is mostly useful when using Relevanssi without a search term where you’ll trigger Relevanssi based on active query variables.

relevanssi_show_matches ($matches)
If you use the “Show breakdown of search hits in excerpts” option, this filter lets you modify the breakdown before it is added to the excerpt.

relevanssi_stemmer ($token) (Premium only)
This hook is used to add a stemmer (or anything else that needs to process every search term and indexed word). Relevanssi Premium comes with a simple English stemmer (actually a suffix stripper), which you can enable:

add_function('relevanssi_stemmer', 'relevanssi_simple_english_stemmer');

relevanssi_term_add_data ($term, $taxonomy) (Premium only)
Use this filter to add extra data to taxonomy term objects before they are indexed.

relevanssi_user_add_data ($user) (Premium only)
Use this filter to add extra data to user objects before they are indexed.

relevanssi_user_searches_capability (‘edit_pages’)
The capability level required to access the User Searches page.

relevanssi_where ($query_restrictions)
The way Relevanssi works is to search for the terms in the index, with a bunch of restrictions to restrict the search to certain post IDs (or to exclude particular post IDs). This filter gives you a chance to examine and modify those restrictions before they are used.