dxw3 Quick Search Pro Hooks

Endpoint Hooks

Standalone endpoint filters are loaded from:

wp-content/dxw3-qs-filters/dxw3-qs-endpoint-filters.php

The plugin automatically creates the directory and a sample filter file during activation if they do not already exist.

<?php
/**
 * Quick Search Pro endpoint filters.
 *
 * This file is loaded by the standalone endpoint.
 * WordPress functions may not be available here.
 */

/*
dxw3_add_filter(
	'dxw3_qs_product_query_results',
	function( $results, $term_id, $orderby, $context ) {
		return $results;
	},
	10
);
*/

Because the file is stored outside the plugin directory, custom endpoint filters are preserved during plugin updates.

WordPress and WooCommerce functions may not be available inside the standalone endpoint filter file. Use dxw3_add_filter() and the provided $context helper methods instead.

Filter Hooks

dxw3_add_filter(
	'dxw3_qs_product_query_results',
	function( $results, $term_id, $orderby, $context ) {
		return $results;
	},
	10
);

Filters the endpoint product query result before product IDs are returned.

Example:

/**
 * Hide endpoint products without price, image, or stock.
 *
 * @param array  $results Query result containing product IDs and total count.
 * @param int    $term_id Selected category term ID.
 * @param string $orderby Current sorting key.
 * @param object $context Endpoint context/helper object.
 *
 * @return array
 */
dxw3_add_filter(
	'dxw3_qs_product_query_results',
	function( $results, $term_id, $orderby, $context ) {
		$flat_table = $context->get_index_table();

		$valid_ids = $context->query_col_int(
			"
			SELECT DISTINCT product_id
			FROM {$flat_table}
			WHERE min_price IS NOT NULL
				AND min_price > 0
				AND thumbnail_id IS NOT NULL
				AND thumbnail_id != 0
				AND total_stock IS NOT NULL
				AND total_stock > 0
			"
		);

		if ( empty( $valid_ids ) ) {
			$results['ids']   = array();
			$results['total'] = 0;

			return $results;
		}

		$valid_lookup = array_flip( array_map( 'intval', $valid_ids ) );

		$results['ids'] = array_values(
			array_filter(
				array_map( 'intval', $results['ids'] ?? array() ),
				function( $id ) use ( $valid_lookup ) {
					return isset( $valid_lookup[ $id ] );
				}
			)
		);

		$results['total'] = count( $results['ids'] );

		return $results;
	},
	10
);

Endpoint filters are added with dxw3_add_filter() and should use the provided $context helper instead of WordPress or WooCommerce functions.

dxw3_add_filter(
	'dxw3_qs_order_clause',
	function( $clause, $orderby, $context ) {
		return $clause;
	},
	10
);

Filters the SQL ORDER BY clause used for endpoint product sorting.

Example:

/**
 * Prioritize in-stock endpoint products.
 */
dxw3_add_filter(
	'dxw3_qs_order_clause',
	function( $clause, $orderby, $context ) {
		if ( '' === $orderby || 'default' === $orderby ) {
			return '
				ORDER BY
					CASE
						WHEN f.total_stock >= 4 THEN 0
						WHEN f.total_stock BETWEEN 1 AND 3 THEN 1
						ELSE 2
					END ASC,
					f.product_title ASC,
					f.product_id DESC
			';
		}

		return $clause;
	},
	10
);

The returned SQL string should include the ORDER BY keyword.

dxw3_add_filter(
	'dxw3_qs_product_is_visible',
	function( $visible, $product_id, $row, $context ) {
		return $visible;
	},
	10
);

Controls whether an individual endpoint product is rendered in Quick Search results.

Example:

/**
 * Hide products with no stock from endpoint results.
 */
dxw3_add_filter(
	'dxw3_qs_product_is_visible',
	function( $visible, $product_id, $row, $context ) {
		$total_stock = isset( $row['total_stock'] ) ? (int) $row['total_stock'] : 0;

		if ( $total_stock <= 0 ) {
			return false;
		}

		return $visible;
	},
	10
);

Useful for hiding products based on stock, tags, customer groups, or custom endpoint logic.

dxw3_add_filter(
	'dxw3_qs_adjust_min_price',
	function( $price, $product_id, $context ) {
		return $price;
	},
	10
);

Filters the minimum product price displayed in endpoint Quick Search results.

Example:

/**
 * Apply a custom endpoint discount to minimum prices.
 */
dxw3_add_filter(
	'dxw3_qs_adjust_min_price',
	function( $price, $product_id, $context ) {
		$customer_group = $context->dxw3_get_context_value( 'customer_group', 'consumer' );

		if ( 'vip' === $customer_group ) {
			$price -= 5;
		}

		return max( 0, $price );
	},
	10
);

Useful for customer-group pricing, discounts, or custom frontend-only price adjustments.

dxw3_add_filter(
	'dxw3_qs_adjust_max_price',
	function( $price, $product_id, $context ) {
		return $price;
	},
	10
);

Filters the maximum product price displayed in endpoint Quick Search results.

Example:

/**
 * Apply a custom endpoint discount to maximum prices.
 */
dxw3_add_filter(
	'dxw3_qs_adjust_max_price',
	function( $price, $product_id, $context ) {
		$customer_group = $context->dxw3_get_context_value( 'customer_group', 'consumer' );

		if ( 'vip' === $customer_group ) {
			$price -= 5;
		}

		return max( 0, $price );
	},
	10
);

Useful for customer-group pricing, discounts, or custom frontend-only price adjustments.

dxw3_add_filter(
	'dxw3_qs_product_extra_info',
	function( $html, $product_id, $row, $context ) {
		return $html;
	},
	10
);

Adds custom HTML below the product price in endpoint Quick Search results.

Example:

/**
 * Add a set price below endpoint product prices.
 */
dxw3_add_filter(
	'dxw3_qs_product_extra_info',
	function( $html, $product_id, $row, $context ) {
		$min_price = isset( $row['min_price'] ) ? (float) $row['min_price'] : 0;

		if ( $min_price <= 0 ) {
			return $html;
		}

		$quantity        = 4;
		$set_price       = $min_price * $quantity;
		$formatted_price = number_format( $set_price, 2, ',', ' ' ) . ' €';

		$html .= '<div class="dxw3-qs-set-price">';
		$html .= htmlspecialchars( $quantity . ' pcs: ', ENT_QUOTES, 'UTF-8' );
		$html .= htmlspecialchars( $formatted_price, ENT_QUOTES, 'UTF-8' );
		$html .= '</div>';

		return $html;
	},
	10
);

Useful for set prices, delivery messages, stock labels, campaign badges, or other lightweight product metadata.

dxw3_add_filter(
	'dxw3_qs_valid_value_limit',
	function( $limit, $slug, $type, $context ) {
		return $limit;
	},
	10
);

Filters the maximum number of valid filter values shown for an Endpoint dropdown.

Example:

/**
 * Disable valid value limits for selected Endpoint filters.
 */
dxw3_add_filter(
	'dxw3_qs_valid_value_limit',
	function( $limit, $slug, $type, $context ) {
		if ( 'att_brand' === $slug ) {
			return 0;
		}

		return $limit;
	},
	10
);

Useful for controlling large dropdowns, performance optimization, or selectively disabling valid value limits.

dxw3_add_filter(
	'dxw3_qs_is_numeric_filter',
	function( $is_numeric, $slug, $context ) {
		return $is_numeric;
	},
	10
);

Determines whether an Endpoint filter should use numeric sorting instead of alphabetical sorting.

Example:

/**
 * Enable numeric sorting for selected Endpoint filters.
 */
dxw3_add_filter(
	'dxw3_qs_is_numeric_filter',
	function( $is_numeric, $slug, $context ) {
		$numeric_slugs = array(
			'att_product-width',
			'att_product-length',
			'att_product-size',
		);

		return in_array( $slug, $numeric_slugs, true );
	},
	10
);

Useful for sizes, dimensions, measurements, offsets, or other filters where numeric ordering is preferred.

WordPress Hooks

Action Hooks

do_action( 'dxw3_qs_pre_query_full', $term_id, $orderby, $instance );

Runs before the full Quick Search product query is executed.

Example:

/**
 * Log full Quick Search queries.
 *
 * @param int                $term_id  Selected category term ID.
 * @param string             $orderby  Current sorting key.
 * @param dxw3_QS_Pro_Public $instance Quick Search Pro public instance.
 *
 * @return void
 */
function dxw3_log_full_quick_search_query( $term_id, $orderby, $instance ) {
	error_log(
		sprintf(
			'Quick Search full query: term_id=%d, orderby=%s',
			(int) $term_id,
			sanitize_text_field( $orderby )
		)
	);
}
add_action( 'dxw3_qs_pre_query_full', 'dxw3_log_full_quick_search_query', 10, 3 );

Useful for logging, analytics, debugging, or custom query preparation logic.

do_action( 'dxw3_qs_pre_query_filtered', $term_id, $orderby, $context );

Runs before the filtered Quick Search product query is executed.

Example:

/**
 * Log filtered Quick Search queries.
 *
 * @param int    $term_id Selected category term ID.
 * @param string $orderby Current sorting key.
 * @param dxw3_QS_Pro_Public $instance Quick Search Pro public instance.
 *
 * @return void
 */
function dxw3_log_filtered_quick_search_query( $term_id, $orderby, $instance ) {
	error_log(
		sprintf(
			'Quick Search filtered query: term_id=%d, orderby=%s',
			(int) $term_id,
			sanitize_text_field( $orderby )
		)
	);
}
add_action( 'dxw3_qs_pre_query_filtered', 'dxw3_log_filtered_quick_search_query', 10, 3 );

Useful for logging, analytics, debugging, or custom filtering-related logic.

do_action( 'dxw3_qs_notification' );

Runs inside the Quick Search controls area between the category filters and sorting dropdown.

/**
 * Add a custom help button to Quick Search controls.
 *
 * @return void
 */
function dxw3_add_quick_search_help_button() {
	echo '<button type="button" class="dxw3-qs-help-btn">';
	echo esc_html__( 'Search Help', 'my-theme' );
	echo '</button>';
}
add_action( 'dxw3_qs_notification', 'dxw3_add_quick_search_help_button' );

Useful for notices, custom buttons, campaign messages, or additional Quick Search controls.

Filter Hooks

apply_filters( 'dxw3_qs_frontend_context', array() );

Adds custom context data to Quick Search frontend requests. This context can be read by AJAX or endpoint filters, for example to apply customer-group-specific filtering or pricing.

Example:

add_filter( 'dxw3_qs_frontend_context', function( $context ) {
	$context['customer_group'] = function_exists( 'my_site_get_customer_group' )
	? my_site_get_customer_group()
	: 'consumer';

	return $context;
} );

apply_filters( 'dxw3_qs_product_query_results_full', $results, $term_id, $orderby, $instance );

Filters the product query result before product IDs are returned. Applies to all query paths: initial load, category navigation, and filtered results.

Example:

/**
 * Remove products without stock from the full Quick Search result set.
 *
 * @param array              $results   Query result containing product IDs and total count.
 * @param int                $term_id  Selected category term ID.
 * @param string             $orderby  Current sorting key.
 * @param dxw3_QS_Pro_Public $instance Quick Search Pro public instance.
 *
 * @return array
 */
function dxw3_filter_full_quick_search_results( $results, $term_id, $orderby, $instance ) {
	$results['ids'] = array_filter(
		array_map( 'absint', $results['ids'] ?? array() ),
		function( $product_id ) {
			$product = wc_get_product( $product_id );

			return $product && $product->is_in_stock();
		}
	);

	$results['ids']   = array_values( $results['ids'] );
	$results['total'] = count( $results['ids'] );

	return $results;
}
add_filter( 'dxw3_qs_product_query_results_full', 'dxw3_filter_full_quick_search_results', 10, 4 );

apply_filters( 'dxw3_qs_order_clause', $clause, $orderby );

Filters the SQL ORDER BY clause used for Quick Search product sorting.

Example:

/**
 * Prioritize in-stock products in Quick Search sorting.
 *
 * @param string $clause  Generated SQL ORDER BY clause.
 * @param string $orderby Current sorting key.
 *
 * @return string
 */
function dxw3_custom_quick_search_order_clause( $clause, $orderby ) {
	if ( '' === $orderby || 'default' === $orderby ) {
		return '
			ORDER BY
				CASE
					WHEN f.total_stock >= 4 THEN 0
					WHEN f.total_stock BETWEEN 1 AND 3 THEN 1
					ELSE 2
				END ASC,
				f.product_title ASC
		';
	}

	return $clause;
}
add_filter( 'dxw3_qs_order_clause', 'dxw3_custom_quick_search_order_clause', 10, 2 );

apply_filters( 'dxw3_qs_product_is_visible', true, $product->product_id, $product );

Controls whether an individual product is rendered in Quick Search results.

Example:

/**
 * Hide products with a specific tag from Quick Search results.
 *
 * @param bool   $visible    Whether the product should be shown.
 * @param int    $product_id Product ID.
 * @param object $product    Product row from the Quick Search index table.
 *
 * @return bool
 */
function dxw3_hide_tagged_products_from_quick_search( $visible, $product_id, $product ) {
	if ( has_term( 'hidden-from-search', 'product_tag', $product_id ) ) {
		return false;
	}

	return $visible;
}
add_filter( 'dxw3_qs_product_is_visible', 'dxw3_hide_tagged_products_from_quick_search', 10, 3 );

This filter runs during product rendering. For large catalog exclusions, filtering the query result earlier may be more efficient.

apply_filters( 'dxw3_qs_adjust_min_price', (float) $product->min_price, $product->product_id );

Filters the minimum product price displayed in Quick Search results.

Example:

/**
 * Apply a custom discount to Quick Search minimum prices.
 *
 * @param float $price      Product minimum price.
 * @param int   $product_id Product ID.
 *
 * @return float
 */
function dxw3_adjust_quick_search_min_price( $price, $product_id ) {
	if ( has_term( 'special-offer', 'product_tag', $product_id ) ) {
		$price = $price - 5;
	}

	return max( 0, $price );
}
add_filter( 'dxw3_qs_adjust_min_price', 'dxw3_adjust_quick_search_min_price', 10, 2 );

Useful for B2B pricing, discounts, or custom frontend-only price adjustments.

apply_filters( 'dxw3_qs_adjust_max_price', (float) $product->max_price, $product->product_id );

Filters the maximum product price displayed in Quick Search results.

Example:

/**
 * Apply a custom discount to Quick Search maximum prices.
 *
 * @param float $price      Product maximum price.
 * @param int   $product_id Product ID.
 *
 * @return float
 */
function dxw3_adjust_quick_search_max_price( $price, $product_id ) {
	if ( has_term( 'special-offer', 'product_tag', $product_id ) ) {
		$price = $price - 5;
	}

	return max( 0, $price );
}
add_filter( 'dxw3_qs_adjust_max_price', 'dxw3_adjust_quick_search_max_price', 10, 2 );

Useful for B2B pricing, discounts, or custom frontend-only price adjustments.

apply_filters( 'dxw3_qs_product_extra_info', '', $product->product_id, $product, $min_price, $max_price );

Adds custom HTML content below the product price in Quick Search results.

Example:

/**
 * Add delivery information to Quick Search products.
 *
 * @param string $html       Existing extra info HTML.
 * @param int    $product_id Product ID.
 * @param object $product    Product row from the Quick Search index table.
 * @param float  $min_price  Minimum product price.
 * @param float  $max_price  Maximum product price.
 *
 * @return string
 */
function dxw3_add_delivery_info_to_quick_search( $html, $product_id, $product, $min_price, $max_price ) {
	if ( $product->total_stock > 0 ) {
		$html .= '<div class="dxw3-qs-delivery-info">Delivery time: 1–3 days</div>';
	} else {
		$html .= '<div class="dxw3-qs-delivery-info">Delivery time: 3–7 days</div>';
	}

	return $html;
}
add_filter( 'dxw3_qs_product_extra_info', 'dxw3_add_delivery_info_to_quick_search', 10, 5 );

Useful for delivery times, campaign labels, stock messages, bundle pricing, or custom product metadata.

apply_filters( 'dxw3_qs_valid_value_limit', 0, $slug, $type, $instance );

Filters the maximum number of valid filter values shown for a Quick Search dropdown.

Example:

/**
 * Disable valid value limits for selected filters.
 *
 * @param int                $limit   Current value limit.
 * @param string             $slug    Filter slug.
 * @param string             $type    Filter type.
 * @param dxw3_QS_Pro_Public $instance Quick Search Pro public instance.
 *
 * @return int
 */
function dxw3_custom_valid_value_limit( $limit, $slug, $type, $instance ) {
	if ( 'att_brand' === $slug ) {
		return 0;
	}

	return $limit;
}
add_filter( 'dxw3_qs_valid_value_limit', 'dxw3_custom_valid_value_limit', 10, 4 );

Useful for controlling large dropdowns, performance optimization, or selectively disabling valid value limits.

apply_filters( 'dxw3_qs_is_numeric_filter', false, $slug, $instance );

Determines whether a Quick Search filter should use numeric sorting instead of alphabetical sorting.

/**
 * Enable numeric sorting for selected filters.
 *
 * @param bool               $is_numeric Whether numeric sorting is enabled.
 * @param string             $slug       Filter slug.
 * @param dxw3_QS_Pro_Public $instance   Quick Search Pro public instance.
 *
 * @return bool
 */
function dxw3_enable_numeric_filter_sorting( $is_numeric, $slug, $instance ) {
	$numeric_slugs = array(
		'att_product-width',
		'att_product-length',
		'att_product-size',
	);

	return in_array( $slug, $numeric_slugs, true );
}
add_filter( 'dxw3_qs_is_numeric_filter', 'dxw3_enable_numeric_filter_sorting', 10, 3 );

Useful for tire sizes, dimensions, measurements, offsets, or other filters where numeric ordering is preferred.

Mini Search Hooks

These WordPress filter hooks are available for the Quick Search Mini widget ([dxw3-quick-search-mini]).

Filter Hooks

apply_filters( 'dxw3_qsm_i18n', $strings );

Filters the UI strings used by the Mini Search widget. Useful for multilingual sites or custom label overrides.

Default value:

array(
'count_suffix' => __( 'products', 'dxw3-quick-search-pro' ),
'select_all'   => __( 'Select all', 'dxw3-quick-search-pro' ),
'no_products'  => __( 'No products', 'dxw3-quick-search-pro' ),
)

Example:

/**
 * Override Mini Search UI strings.
 *
 * @param array $strings Associative array of UI strings.
 *
 * @return array
 */
add_filter( 'dxw3_qsm_i18n', function( $strings ) {
$strings['count_suffix'] = 'items';
$strings['select_all']   = 'All';
$strings['no_products']  = 'Nothing found';

return $strings;
} );

Useful for custom labels, multilingual overrides, or rebranding the Mini Search widget text.

apply_filters( 'dxw3_qsm_groups', $groups, $atts );

Defines search groups for the Mini Search widget. Return a non-empty array to activate multi-group mode. Each group must include a key, label, target_url, and an array of options (each with value and label).

Example:

/**
 * Add predefined search groups to the Mini Search widget.
 *
 * @param array $groups Empty by default. Return a non-empty array to activate.
 * @param array $atts   Sanitised shortcode attributes.
 *
 * @return array
 */
add_filter( 'dxw3_qsm_groups', function( $groups, $atts ) {
return array(
array(
'key'        => 'tyres',
'label'      => 'Car Tyres',
'target_url' => home_url( '/car-tyres/' ),
'options'    => array(
array( 'value' => 'summer', 'label' => 'Summer' ),
array( 'value' => 'winter', 'label' => 'Winter' ),
array( 'value' => 'all-season', 'label' => 'All Season' ),
),
),
);
}, 10, 2 );

Useful for configuring the Mini Search widget with site-specific product groups, categories, or navigation targets.

Indexer Hooks

These WordPress filter hooks run at index-build time, not during frontend requests. They control which products are included in the Quick Search index during a full rebuild or a single-product reindex triggered by a post save.

Filter Hooks

apply_filters( 'dxw3_qs_exclude_product_ids', array(), $product_ids, $source );

Called during a full index rebuild. Return an array of product IDs that should be excluded from the index. The returned IDs are removed from the eligible-product pool before canonical eligibility rules are applied.

Parameters:

• array $excluded_ids — IDs to exclude. Start as an empty array; merge or replace as needed.
• array $product_ids — All candidate product IDs collected from the category map.
• string $source — Context identifier. Currently always 'admin_rebuild'.

Example:

/**
 * Exclude discontinued products from the Quick Search index.
 *
 * @param array  $excluded_ids IDs already scheduled for exclusion.
 * @param array  $product_ids  All candidate product IDs.
 * @param string $source       Context identifier ('admin_rebuild').
 *
 * @return array
 */
add_filter( 'dxw3_qs_exclude_product_ids', function( $excluded_ids, $product_ids, $source ) {
$discontinued = get_posts( array(
'post_type'      => 'product',
'posts_per_page' => -1,
'fields'         => 'ids',
'meta_key'       => '_discontinued',
'meta_value'     => '1',
) );

return array_merge( $excluded_ids, $discontinued );
}, 10, 3 );

This filter runs during full rebuild only. For per-product eligibility control on save, use dxw3_qs_should_index_product.

apply_filters( 'dxw3_qs_should_index_product', $should_index, $product_id, $source );

Called during single-product reindexing (triggered by a post save). Return false to prevent the product from being written to the index. The default value is the result of the canonical eligibility check: price > 0, thumbnail present, belongs to an indexed category, not excluded from catalog.

Parameters:

• bool $should_index — Whether the product passes canonical eligibility.
• int $product_id — The product post ID being evaluated.
• string $source — Context identifier. Currently always 'save' for post-save reindexing.

Example:

/**
 * Prevent B2B-only products from being indexed for public search.
 *
 * @param bool   $should_index Whether the product passes canonical eligibility.
 * @param int    $product_id   The product post ID.
 * @param string $source       Context identifier ('save').
 *
 * @return bool
 */
add_filter( 'dxw3_qs_should_index_product', function( $should_index, $product_id, $source ) {
if ( get_post_meta( $product_id, '_b2b_only', true ) === '1' ) {
return false;
}

return $should_index;
}, 10, 3 );

This filter runs on post save only. For bulk exclusion during a full rebuild, use dxw3_qs_exclude_product_ids.