`\SearchWP\Mod`

Table of Contents

Basic Usage
Arguments
Methods

\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:

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

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

	<?php
	// @link https://searchwp.com/documentation/classes/searchwp-mod/
	$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:

	<?php
	// @link https://searchwp.com/documentation/classes/searchwp-mod/
	// 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.

view raw searchwp-mod-searchwp-query.php hosted with ❤ by GitHub

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.

	<?php
	// @link https://searchwp.com/documentation/classes/searchwp-mod/
	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.

view raw searchwp-mod-hook.php hosted with ❤ by GitHub

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

Arguments

\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:

	<?php
	// @link https://searchwp.com/documentation/classes/searchwp-mod/
	// 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)

Methods

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.
get_columns(): Getter for registered columns.
get_weights(): Getter for registered weight modifications.
get_join_sql(): Getter for generated JOIN SQL.
raw_join_sql( $sql ): Adds raw JOIN SQL clause.
get_raw_join_sql(): Getter for raw JOIN SQL clauses.
raw_where_sql( $sql ): Adds raw WHERE SQL clause.
get_raw_where_sql(): Getter for raw WHERE SQL clauses.
get_source(): Getter for applicable \SearchWP\Source.
set_where( $where ): Setter for WHERE clauses.
get_where(): Getter for WHERE clauses.
set_local_table( string $table ): Setter for local table name.
get_local_table(): Getter for local table name.
set_local_table_alias( string $table ): Setter for local table alias.
get_local_table_alias(): Getter for local table alias.
set_foreign_alias( string $alias ): Setter for foreign table alias.
get_foreign_alias(): Getter for foreign table alias.
on( string $local, array $foreign ): Adds ON clause.
get_on(): Getter for ON clauses.
order_by( $column, $direction, $priority ): Adds ORDER BY clause. Example
get_order_by(): Getter for ORDER BY clauses.
set_values( array $values ): Setter for SQL placeholder values to be escaped at runtime.
get_values(): Getter for SQL placeholder values.

\SearchWP\Mod

Basic Usage

Arguments

Methods

Create a Better WordPress Search Experience Today

`\SearchWP\Mod`