Relevanssi

https://www.relevanssi.com/user-manual/
Admin
Relevanssi is a WordPress search plugin that improves site search with advanced features like phrase...
Tokens:222,282
Snippets:1,636
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Add extra content from database table with relevanssi_content_to_index

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_content_to_index

Basic example of fetching data from a database table and appending it to the content. The $content starts empty, but it's best to append with a leading space to avoid issues if other filters have added content. The index is only updated when the post is saved or the index is rebuilt.

```php
add_filter( 'relevanssi_content_to_index', 'rlv_add_extra_content', 10, 2 );
function rlv_add_extra_content( $content, $post ) {
    global $wpdb;
    $content .= ' ' . $wpdb->get_var( "SELECT data FROM extra_table WHERE post_id = $post->ID" );
    return $content;
}
```

--------------------------------

### relevanssi_pre_indexing_query action hook example

Source: https://www.relevanssi.com/user-manual/filter-hooks

An example of using the relevanssi_pre_indexing_query action hook to set the SQL_BIG_SELECTS option. Note that this hook runs before indexing, not during searches, so it will not affect search queries.

```php
function relevanssi_pre_indexing_query_action_hook( ) {
    global $wpdb;
    $wpdb->query('SET SQL_BIG_SELECTS=1');
}
add_action( 'relevanssi_pre_indexing_query', 'relevanssi_pre_indexing_query_action_hook' );
```

--------------------------------

### Bulk Add via CSV example

Source: https://www.relevanssi.com/user-manual/redirects

Example of semicolon-separated redirect rules for the Bulk Add via CSV panel. Each line contains query, destination URL, and partial matching flag (1 enables, 0 or omitted disables). Leading and trailing spaces are removed; no header row or quoted fields.

```csv
jobs;/careers/;0
hours;/opening-hours/;1
address;/contact/;0
```

--------------------------------

### relevanssi_multi_results filter example with switch_to_blog

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_multi_results

Multisite version of the date-based weight filter using relevanssi_multi_results. It parses the blog ID from the key, switches to that blog to get the post date, and restores the current blog afterward. This avoids the need for a separate relevanssi_results filter on each subsite.

```php
add_filter( 'relevanssi_multi_results', 'date_weights' );
function date_weights( $results ) {
	array_walk(
        $results,
        function( &$weight, $blog_post_id ) {
            list ( $blog_id, $post_id ) = explode( '|', $blog_post_id );
            switch_to_blog( $blog_id );
            $post_date = get_the_time( 'U', $post_id );
	        if ( time() - $post_date < WEEK_IN_SECONDS ) {
 		        $weight = $weight * 2;
            } else {
                $weight = $weight / 2;
            }
            restore_current_blog();
        }
    );
    return $results;
}
```

--------------------------------

### Example suggestion HTML output

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_didyoumean_suggestion

Shows the HTML structure of the suggestion that the filter receives.

```html
<p>Did you mean: <a href="http://loyang.local?s=lore">lore</a></p>
```

--------------------------------

### Whitelist rlv_source values with relevanssi_valid_sources filter

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_valid_sources

Example of using the relevanssi_valid_sources filter to whitelist allowed source values. Any values not in the returned array will be ignored.

```php
add_filter( 'relevanssi_valid_sources', function( $sources ) {
  return array( 'main', 'sidebar', 'knowledgebase' );
} );
```

--------------------------------

### All-in-One SEO indexing restriction example

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_indexing_restriction

Example filter function that adds a restriction to exclude posts with robots_noindex set to 1 in the aioseo_posts table. Uses .= to append to existing restrictions and adds a reason string.

```php
function relevanssi_aioseo_exclude( array $restriction ) {
	if ( 'on' !== get_option( 'relevanssi_seo_noindex' ) ) {
		return $restriction;
	}

	global $wpdb;

	$restriction['mysql']  .= " AND post.ID NOT IN (SELECT post_id FROM
		{$wpdb->prefix}aioseo_posts WHERE robots_noindex = '1' ) ";
	$restriction['reason'] .= ' All-in-One SEO';

	return $restriction;
}
```

--------------------------------

### relevanssi_substr($str, $start, $length = null)

Source: https://www.relevanssi.com/user-manual/functions

Returns a substring beginning at $start, with an optional maximum length. Uses multibyte handling when available; a null length takes the remainder of the string.

```APIDOC
## relevanssi_substr($str, $start, $length = null)

### Description
Returns a substring beginning at $start, with an optional maximum length. Uses multibyte handling when available; a null length takes the remainder of the string.

### Method
Function

### Signature
`relevanssi_substr($str, $start, $length = null)`

### Parameters
- **$str** (string) - Required - The string to extract from.
- **$start** (int) - Required - The starting position.
- **$length** (int|null) - Optional - The maximum length of the substring. Default null (to end of string).

### Returns
- **string** - The extracted substring.
```

--------------------------------

### apply_filters( 'relevanssi_valid_sources', array $sources )

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_valid_sources

Documentation for the relevanssi_valid_sources filter hook, including parameters and usage examples.

```APIDOC
## apply_filters( 'relevanssi_valid_sources', array $sources )

### Description
Filters the valid source parameters for log filtering. This hook allows you to whitelist the values that can be used with the `rlv_source` parameter in search forms, which is used to filter user search logs.

### Parameters
- **$sources** (array) - A list of string values that are whitelisted for the source parameter.

### Usage Example
```php
add_filter( 'relevanssi_valid_sources', function( $sources ) {
  return array( 'main', 'sidebar', 'knowledgebase' );
} );
```

### More Information
Relevanssi Premium 2.27.0 added a new feature that allows you to mark your search forms with a `rlv_source` parameter and then filter your user search logs based on those values. To add the parameter, add a `rlv_source` parameter to your search form. If you use the `searchform` shortcode, you can add `rlv_source="keyword"` to the shortcode parameters, or you can use a hidden input field in the search form:

```html
<input type="hidden" name="rlv_source" value="keyword" />
```

Because these values are entered directly into your `wp_relevanssi_log` database table, there’s an extra layer of security. You must use this filter hook to whitelist all possible values; any other values will be ignored.
```

--------------------------------

### relevanssi_fallback filter example (Jonathan's attempt)

Source: https://www.relevanssi.com/user-manual/filter-hooks

A user's initial attempt to use the relevanssi_fallback filter, which only adjusts the query parameter but does not run the search. This is incomplete and will not work as intended.

```php
add_filter( 'relevanssi_fallback', 'fallback_search' );
function fallback_search( $args ) {
    $args['args']['q'] = "pictures";
    return $args;
}
```

--------------------------------

### relevanssi_fallback filter example (corrected by Mikko Saari)

Source: https://www.relevanssi.com/user-manual/filter-hooks

Corrected version of the relevanssi_fallback filter that runs the search using relevanssi_search() and returns the updated parameters. This is the recommended way to implement a fallback search.

```php
add_filter( 'relevanssi_fallback', 'fallback_search' );
function fallback_search( $params ) {
    $params['args']['q'] = 'pictures';
    $params['return']    = relevanssi_search( $params['args'] );
    return $params;
}
```

--------------------------------

### Fetch external content for indexing and excerpts with separate functions

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_content_to_index

Performance-conscious example: uses separate functions for indexing and excerpts. The indexing function fetches external content and caches it in post meta; the excerpt function reads from that cache to avoid slow remote requests on every search.

```php
add_filter( 'relevanssi_content_to_index', 'rlv_add_external_content', 10, 2 );
function rlv_add_external_content( $content, $post ) {
  $url = get_post_meta( $post->ID, 'external_content_url', true );
  if ( filter_var( $url, FILTER_VALIDATE_URL ) !== false ) { 
    $response = wp_remote_get( $url );
    if ( is_wp_error( $response ) ) {
      return $content;
    }
    $body     = wp_remote_retrieve_body( $response );
    $content .= ' ' . $body;
    update_post_meta( $post->ID, '_external_content_body', $body );
    return $content;
}

add_filter( 'relevanssi_excerpt_content', 'rlv_excerpt_external_content', 10, 2 );
function rlv_excerpt_external_content( $content, $post ) {
    $content .= ' ' . get_post_meta( $post->ID, '_external_content_body', true );
    return $content;
}
```

--------------------------------

### Boost in-stock product weight with relevanssi_match filter

Source: https://www.relevanssi.com/user-manual/woocommerce

Adds a filter on 'relevanssi_match' to multiply the weight of in-stock products by 10. Products with the 'outofstock' term in 'product_visibility' are considered out of stock. Warning: this is likely a major performance problem; see linked documentation for faster alternatives.

```PHP
add_filter( 'relevanssi_match', 'rlv_woo_stocklevel' );
function rlv_woo_stocklevel( $match ) {
    $in_stock = true;
    if ( has_term( 'outofstock', 'product_visibility', $match->doc ) ) {
      // Product is not in stock.
      $in_stock = false;
    }
    if ( $in_stock ) {
      // If product is in stock, multiply the weight by 10.
      $match->weight *= 10;
    }
    return $match;
}
```

--------------------------------

### Initial indexing query

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_indexing_query

Default MySQL query for fetching posts during initial indexing. Filters post statuses and handles inherit posts with parent status checks.

```sql
SELECT post.ID
  FROM wp_posts post
  LEFT JOIN wp_posts parent ON (post.post_parent=parent.ID)
  WHERE
    (post.post_status IN ('publish','draft','private')
      OR
      (post.post_status='inherit' AND(
        (parent.ID is not null AND (parent.post_status IN ('publish','draft','private')))
        OR (post.post_parent=0)
      ))
    )
  ORDER BY post.ID DESC
```

--------------------------------

### relevanssi_results filter example for date-based weight adjustment

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_multi_results

Example of a relevanssi_results filter that adjusts weights based on post age. It doubles the weight for posts from the last week and halves it for older posts. This is the single-site version that does not handle blog IDs.

```php
add_filter( 'relevanssi_results', 'date_weights' );
function date_weights( $results ) {
	array_walk(
        $results,
        function( &$weight, $post_id ) {
            $post_date = get_the_time( 'U', $post_id );
	        if ( time() - $post_date < WEEK_IN_SECONDS ) {
 		        $weight = $weight * 2;
            } else {
                $weight = $weight / 2;
            }
        }
    );
    return $results;
}
```

--------------------------------

### Enable excerpt optimization with relevanssi_optimize_excerpts

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_optimize_excerpts

Add this to your theme's functions.php to enable excerpt optimization, preferring speed over quality. The hook returns `true` to activate the optimization.

```PHP
add_filter( 'relevanssi_optimize_excerpts', '__return_true' );
```

--------------------------------

### Customize missing terms template with add_filter

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_missing_terms_template

Example of using the 'relevanssi_missing_terms_template' filter to change the template for the missing terms list. The example replaces the default span with a ul element, and also changes the tag for individual terms using 'relevanssi_missing_terms_tag'.

```PHP
add_filter( 'relevanssi_missing_terms_template', 'rlv_terms_template' );
function rlv_terms_template( $template ) {
  return '<ul class="missing_terms">%s</ul>';
}

add_filter( 'relevanssi_missing_terms_tag', function( $tag ) { return 'li'; } );
```

--------------------------------

### Add post_type parameter to Did you mean URL with relevanssi_didyoumean_url

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_didyoumean_url

PHP example that hooks into `relevanssi_didyoumean_url` to add a `post_type` parameter to the suggestion URL using `add_query_arg()`. The example defines a callback function `rlv_add_dym_parameters` that returns the modified URL. Note that complex parameters should be `urlencode()`d.

```PHP
add_filter( 'relevanssi_didyoumean_url', 'rlv_add_dym_parameters' );
function rlv_add_dym_parameters( $url ) {
  return add_query_arg( 'post_type', 'product', $url );
}
```

--------------------------------

### relevanssi_rendered_block

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_rendered_block

Documentation for the 'relevanssi_rendered_block' filter hook, including parameters and an example usage.

```APIDOC
## apply_filters( 'relevanssi_rendered_block', string $content, array $block )

### Description
Filters Gutenberg blocks after they are rendered. This hook allows modification of the block content before Relevanssi indexes it.

### Parameters
- **$content** (string) - Required - The rendered block content from `render_block()`.
- **$block** (array) - Required - The block array.

### Example
```php
add_filter( 'relevanssi_rendered_block', 'rlv_modify_block_content', 10, 2 );
function rlv_modify_block_content( $content, $block ) {
  if ( 'custom/blockname' === $block['blockName'] ) {
    $content = str_replace( 'foo', 'bar', $content );
  }
  return $content;
}
```
```

--------------------------------

### relevanssi_build_index($extend_offset = false, $verbose = null, $post_limit = null, $is_ajax = false)

Source: https://www.relevanssi.com/user-manual/functions

Builds the index using saved indexing rules. The default false $extend_offset clears the existing index first; true extends without clearing, and a numeric offset continues from that position. $verbose is retained for compatibility and is no longer used. $post_limit limits the batch. Returns completion and indexed-post counts; Ajax context uses named keys. Changes stored data.

```APIDOC
## relevanssi_build_index($extend_offset = false, $verbose = null, $post_limit = null, $is_ajax = false)

### Description
Builds the index using saved indexing rules. The default false $extend_offset clears the existing index first; true extends without clearing, and a numeric offset continues from that position. $verbose is retained for compatibility and is no longer used. $post_limit limits the batch. Returns completion and indexed-post counts; Ajax context uses named keys. Changes stored data.

### Parameters
- **$extend_offset** (bool|int) - Optional - Default false. If false, clears the existing index first. If true, extends without clearing. If numeric, continues from that offset.
- **$verbose** (mixed) - Optional - Retained for compatibility, no longer used.
- **$post_limit** (int|null) - Optional - Limits the batch size.
- **$is_ajax** (bool) - Optional - Default false. If true, returns named keys in Ajax context.

### Returns
- (array) Completion and indexed-post counts. In Ajax context, uses named keys.
```

--------------------------------

### relevanssi_index_excerpt

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_index_excerpt

Documentation for the relevanssi_index_excerpt filter hook, including parameters and an example usage.

```APIDOC
## apply_filters( 'relevanssi_index_excerpt', bool $index, WP_Post $post_object )

### Description
Controls whether post excerpt is indexed or not. Use this filter hook to set indexing on a per-post basis.

### Parameters
- **$index** (bool) - If `true`, index post content. Default `true`.
- **$post_object** (WP_Post) - The post object.

### Example
```php
add_filter( 'relevanssi_index_excerpt', function( $index, $post_object ) {
    if ( 'post' === $post_object->post_type ) {
        $index = false;
    }
    return $index;
}, 10, 2 );
```
```

--------------------------------

### Set query variables and run Relevanssi query

Source: https://www.relevanssi.com/user-manual/using-relevanssi-outside-search-pages

Sets the search term, posts per page, and page number on a query object, then runs relevanssi_do_query().

```php
$query->query_vars['s'] = 'printer';  
$query->query_vars['posts_per_page'] = 10;  
$query->query_vars['paged'] = 1;  
relevanssi_do_query($query);
```

--------------------------------

### Boost posts with custom field using relevanssi_get_post_meta_for_all_posts()

Source: https://www.relevanssi.com/user-manual/functions/relevanssi_get_post_meta_for_all_posts

More efficient example using the relevanssi_results filter and relevanssi_get_post_meta_for_all_posts() to fetch custom fields for all posts in one query. This triggers once per post and performs only one database query.

```PHP
add_filter( 'relevanssi_results', 'custom_field_weights' );
function custom_field_weights( $results ) {
    $featured = relevanssi_get_post_meta_for_all_posts( array_keys( $results ), 'radio_button_field_button_link', true );
    array_walk(
        $featured,
        function( $value, $post_id ) use ( &$results ) {
            if ( 1 === (int) $value ) {
                $results[ $post_id ] *= 2;
            }
        }
    );
    return $results;
}
```

--------------------------------

### PHP example: Use URL method for a specific attachment

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_send_pdf_files

This filter hook allows per-file control over whether Relevanssi uploads the file or lets the reading server fetch it. The example sets $send_file to false for post ID 42, forcing the URL method. The hook accepts two arguments: $send_file (boolean) and $post_id (int).

```PHP
add_filter( 'relevanssi_send_pdf_files', function( $send_file, $post_id ) {
  if ( 42 === $post_id ) {
    $send_file = false;
  }
  return $send_file;
}, 10, 2 );
```

--------------------------------

### WooCommerce: Call relevanssi_index_doc() on woocommerce_new_product

Source: https://www.relevanssi.com/user-manual/functions/relevanssi_index_doc

Use this action hook to index a product after WooCommerce finishes adding it, ensuring all metadata (like SKU) is indexed. The function is called with the product ID, true, relevanssi_get_custom_fields(), and true.

```PHP
add_action(
  'woocommerce_new_product',
  function( $id ) {
    relevanssi_index_doc( $id, true, relevanssi_get_custom_fields(), true );
  }
);
```

--------------------------------

### Add a bot to the relevanssi_bots_to_not_log list

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_bots_to_not_log

Example of adding a new bot to the blocklist by merging a custom bot entry into the filtered array. The bot's user agent is compared case-insensitively using `stristr()`.

```php
add_filter( 'relevanssi_bots_to_not_log', function( $bots ) {
  return array_merge( $bots, array( 'Bad Bot' => 'BadBot' ) );
} );
```

--------------------------------

### relevanssi_highlight_regex

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_highlight_regex

Documentation for the relevanssi_highlight_regex filter hook, including parameters, usage example, and default regex patterns.

```APIDOC
## apply_filters( 'relevanssi_highlight_regex', string $regex, string $term )

### Description
Filters the regular expression used for adding highlights to the excerpt. This filter hook allows modification of the regex that Relevanssi uses to find search terms in the excerpt for highlighting.

### Parameters
- **$regex** (string) - The regular expression.
- **$term** (string) - The search term.

### Usage Example
```php
add_filter( 'relevanssi_highlight_regex', function( $regex, $term ) {
  return "/($term)/iu";
}, 10, 2 );
```

### More Information
- Default value: `/([\W])($term)([\W])/iu` (whole-word matching).
- With partial matching: `/([\W]{$term}|{$term}[\W])/iu`.
- With "Expand highlights" setting: `/([\w]*{$term}[\W]|[\W]{$term}[\w]*)/iu`.
- When whole-word matching is enabled, the regex needs three capture groups where the term is in the middle one, because the regex is replaced with `'\\1' . $start_highlight_token . '\\2' . $end_highlight_token . '\\3'`. For partial matching, one capture group for the term itself is enough.
```

--------------------------------

### Change threshold with add_filter

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_get_words_having

Example of using the relevanssi_get_words_having filter to change the threshold from 2 to 3. Small increments are recommended.

```php
add_filter( 'relevanssi_get_words_having', function() { return 3; } );
```

--------------------------------

### relevanssi_get_post($post_id, $blog_id = -1)

Source: https://www.relevanssi.com/user-manual/functions

Retrieves a post object, optionally from a different blog. The function is documented as a helper for getting posts.

```APIDOC
## relevanssi_get_post($post_id, $blog_id = -1)

### Description
Retrieves a post object, optionally from a different blog. The function is documented as a helper for getting posts.

### Parameters
- **$post_id** (int) - Required - The post ID.
- **$blog_id** (int) - Optional - Default -1. The blog ID to retrieve the post from.

### Returns
- (object|null) The post object, or null if not found.
```

--------------------------------

### Force highlight and tracking parameters with add_filter

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_add_highlight_and_tracking

Adds the Relevanssi highlight and click tracking parameters to all permalinks by returning true from the filter. This may cause parameters to appear in unintended places, so more finesse may be required.

```php
 add_filter( 'relevanssi_add_highlight_and_tracking', '__return_true' );

```

--------------------------------

### Modify attachment query with relevanssi_get_attachment_posts_query_final

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_get_attachment_posts_query_final

Example using the final filter hook. Allows direct string replacement without worrying about prepared statements.

```php
add_filter( 'relevanssi_get_attachment_posts_query_final', function( $query ) {
  return str_replace(
    "post_type = 'attachment' AND post_status = 'inherit' AND post_mime_type LIKE 'application/%'", 
    "post_type = 'document' AND post_status = 'publish'",
    $query
  );
} );
```

--------------------------------

### apply_filters( 'relevanssi_cached_post_object', stdClass $post )

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_cached_post_object

Filters the post objects as they are cached. Use this hook to modify the post object, for example to convert it to a WP_Post object.

```APIDOC
## apply_filters( 'relevanssi_cached_post_object', stdClass $post )

### Description
Filters the post objects as they are cached. Use this hook to modify the post object, for example to convert it to a WP_Post object.

### Parameters
- **$post** (stdClass) - Required - The post object from `wp_posts` database table.

### Example
```php
add_filter( 'relevanssi_cached_post_object', function( $post ) {
  $post->filter = 'raw'; // You probably want to set this flag.
  return new WP_Post( $post );
} );
```
```

--------------------------------

### Filter relevanssi_admin_search_capability to require publish_posts

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_admin_search_capability

Use this filter to change the minimum capability required to access the Relevanssi admin search page. The example sets the capability to `publish_posts`, which corresponds to the author role. Other options mentioned include `edit_others_posts` for editors, `manage_options` for admins, and `manage_network` for super admins.

```PHP
add_filter( 'relevanssi_admin_search_capability', function ( $capability ) { return 'publish_posts'; } );
```

--------------------------------

### Change the missing terms tag to span

Source: https://www.relevanssi.com/user-manual/filter-hooks/relevanssi_missing_terms_tag

Use this filter to change the HTML tag from the default `s` to `span`. The example uses an anonymous function that returns 'span'.

```php
add_filter( 'relevanssi_missing_terms_tag', function( $tag ) { return 'span'; } );
```

--------------------------------

### Use 'relevanssi' parameter to enable Relevanssi automatically

Source: https://www.relevanssi.com/user-manual/using-relevanssi-outside-search-pages

This snippet achieves the same result as the previous example but is often cleaner. By setting 'relevanssi' to true in the query arguments, Relevanssi automatically takes over and processes the query. This method is equivalent to using relevanssi_do_query().

```PHP
$args = array(
    's'          => 'search terms',
    'relevanssi' => true,
);
$query = new WP_Query( $args );
```

--------------------------------

### relevanssi_the_excerpt()

Source: https://www.relevanssi.com/user-manual/functions

Prints the current object's existing excerpt. Use relevanssi_do_excerpt() to generate an excerpt yourself.

```APIDOC
## relevanssi_the_excerpt()

### Description
Prints the current object's existing excerpt. Use relevanssi_do_excerpt() to generate an excerpt yourself.

### Method
Function

### Output
Prints the existing excerpt.
```
Tokens:
Raw