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:

// @link
$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',
] ] );

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:

// @link
// 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.

// @link
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:

// @link
// 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)


relevance( $sql )
Adds relevance calculation clause. Example
weight( $sql )
Adds weight calculation clause. Note: unlike relevance(), weight calculation is multiplied by the number of search matches.
column_as( $sql, $column_name )
Adds column modification clause.
Getter for registered columns.
Getter for registered weight modifications.
Getter for generated JOIN SQL.
raw_join_sql( $sql )
Adds raw JOIN SQL clause.
Getter for raw JOIN SQL clauses.
raw_where_sql( $sql )
Adds raw WHERE SQL clause.
Getter for raw WHERE SQL clauses.
Getter for applicable \SearchWP\Source.
set_where( $where )
Setter for WHERE clauses.
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.
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.
Getter for SQL placeholder values.