Note: You are viewing the documentation for Version 4View Version 3 Docs


Table of Contents

\SearchWP\Mod objects are used to modify a \SearchWP\Query.

Each \SearchWP\Mod implements a single modification, and any number of \SearchWP\Mods can be used at one time.

Some common use cases for \SearchWP\Mods include:

  • Altering the relevance weight calculation of results based on custom parameters.
  • Controlling what results are returned (or not returned) based on custom criteria.
  • JOINing with custom database tables to implement custom criteria.

More specifically related to Posts, Pages, and Custom Post Types, \SearchWP\Mods can be used to:

  • Limit results to those in a certain Category.
  • Exclude results with a certain Tag.
  • Give extra weight to more recent publish dates.
  • Implement a weight boost based on meta value for posts with a certain Custom Field.
  • Add bonus weight to posts that have a certain taxonomy term.

\SearchWP\Mods allow for interaction with a \SearchWP\Query without having to write custom SQL, although that can be done where applicable when putting together a \SearchWP\Mod or by using a \SearchWP\Query hook.

See also: Comparing Index and Source Mods

Basic Usage

Usage of \SearchWP\Mod varies by use case, but the implementation occurs in one of two ways:

  1. An array of \SearchWP\Mod can be passed to \SearchWP\Query using the 'mods' argument.
  2. Using the searchwp\query\mods hook.

As an example, this \SearchWP\Mod excludes Posts 145 and 211 from search results:

$source = \SearchWP\Utils::get_post_type_source_name( 'post' );
$mod = new \SearchWP\Mod( $source );
$mod->set_where( [ [
'column' => 'id',
'value' => [ 145, 211 ],
'compare' => 'NOT IN',
'type' => 'NUMERIC',
] ] );
view raw searchwp-mod.php hosted with ❤ by GitHub

With the \SearchWP\Mod written, the next step is to implement it by following one of the 2 steps above.

If you are building your own \SearchWP\Query you can pass this \SearchWP\Mod in with the 'mods' argument:

// Retrieve Source name to use with Mod.
$source = \SearchWP\Utils::get_post_type_source_name( 'post' );
// Build Mod to exclude Post ID 145 and Post ID 211.
$mod = new \SearchWP\Mod( $source );
$mod->set_where( [ [
'column' => 'id',
'value' => [ 145, 211 ],
'compare' => 'NOT IN',
'type' => 'NUMERIC',
] ] );
// Execute search for 'coffee' using Mod.
$search = new \SearchWP\Query( 'coffee', [
'mods' => [ $mod ],
] );
$results = $search->results; // Array of results.

Alternatively you can use the searchwp\query\mods hook to enqueue the \SearchWP\Mod.

Note: that when this method is used, this \SearchWP\Mod will be applied to all searches unless additional code is written to prevent that.

add_filter( 'searchwp\query\mods', function( $mods, $query ) {
// Retrieve Source name to use with Mod.
$source = \SearchWP\Utils::get_post_type_source_name( 'post' );
// Build Mod to exclude Post ID 145 and Post ID 211.
$mod = new \SearchWP\Mod( $source );
$mod->set_where( [ [
'column' => 'id',
'value' => [ 145, 211 ],
'compare' => 'NOT IN',
'type' => 'NUMERIC',
] ] );
$mods[] = $mod;
return $mods;
}, 20, 2 );
// Execute search for 'coffee' using Mod enqueued above.
$search = new \SearchWP\Query( 'coffee' );
$results = $search->results; // Array of results.

Using the searchwp\query\mods hook to enqueue a \SearchWP\Mod allows for application during native searches.


\SearchWP\Mod has a single, optional argument: $source.

When a $source is defined, some behavior (e.g. WHERE clauses) will automatically be restricted to the logic for that particular $source.

When a $source is not supplied, that behavior will apply to the index.

For more information please see Comparing Index and Source Mods.

$source can be either the name of a \SearchWP\Source or the \SearchWP\Source itself.

Note: When working with WP_Post Sources you can use this utility method to retrieve the Source name by passing in the post type name:

// Retrieve the Source name for a Post Type:
$source = \SearchWP\Utils::get_post_type_source_name( 'post' ); // Posts.
$source = \SearchWP\Utils::get_post_type_source_name( 'page' ); // Pages.
$source = \SearchWP\Utils::get_post_type_source_name( 'movie' ); // Custom Post Type.
view raw functions.php hosted with ❤ by GitHub

If no $source is provided, sensible defaults will be handled internally during instantiation.

source (string)
The name of the \SearchWP\Source (default: null)


weight( $sql )
Adds weight calculation clause. Example
column_as( $sql, $column_name )
Adds column modification clause. Example
Getter for registered columns.
Getter for registered weight modifications.
Getter for generated JOIN SQL.
raw_join_sql( $sql )
Adds raw JOIN SQL clause. Example
Getter for raw JOIN SQL clauses.
raw_where_sql( $sql )
Adds raw WHERE SQL clause. Example
Getter for raw WHERE SQL clauses.
Getter for applicable \SearchWP\Source.
set_where( $where )
Setter for WHERE clauses. Example
Getter for WHERE clauses.
set_local_table( string $table )
Setter for local table name.
Getter for local table name.
set_local_table_alias( string $table )
Setter for local table alias.
Getter for local table alias.
set_foreign_alias( string $alias )
Setter for foreign table alias.
Getter for foreign table alias.
on( string $local, array $foreign )
Adds ON clause. Example
Getter for ON clauses.
order_by( $column, $direction, $priority )
Adds ORDER BY clause. Example
Getter for ORDER BY clauses.
set_values( array $values )
Setter for SQL placeholder values to be escaped at runtime. Example
Getter for SQL placeholder values.
Fix keyword search on your site. No coding required!

Now you can utilize all of the content that's gone unrecognized by native WordPress keyword search instantly with SearchWP

Get SearchWP