`benecaster_search_pre_results`

Filter Free

A short-circuit filter for the episode search — used by both the search REST endpoint and the benecaster_search shortcode. Return null (the default) to let Benecaster’s own query run. Return a non-null array to bypass Benecaster’s own query entirely and substitute your own result set — useful for routing queries through an external search backend such as Elasticsearch, Typesense, or Algolia.

This is a Free filter. The returned array must include episode_id, title, excerpt, tier_slug, episode_type, and permalink per result item. The benecaster_search_results filter fires afterward regardless of whether results came from Benecaster’s own query or from this short-circuit.

Parameters

Name	Type	Default	Description
`$pre_results`	`array\|null`	—	Default null; return non-null to short-circuit
`$q`	`string`	—	Search term
`$show_id`	`int`	—	Show post ID
`$tiers`	`string[]`	—	Accessible tier slugs for the requester
`$page`	`int`	—	Page number
`$per_page`	`int`	—	Results per page

Returns: array|null

Examples

Route all queries through Typesense

add_filter( 'benecaster_search_pre_results', function( $pre_results, $q, $show_id, $tiers, $page, $per_page ) {
    // Route all search queries through Typesense and bypass Benecaster's own query.
    if ( ! function_exists( 'my_typesense_search' ) ) {
        return null;
    }
    return my_typesense_search( $q, $show_id, $tiers, $page, $per_page );
}, 10, 6 );

Delegate to external backend with SQL fallback

add_filter( 'benecaster_search_pre_results', function( ?array $pre_results, string $q, int $show_id, array $tiers, int $page, int $per_page ): ?array {
    if ( ! my_elasticsearch_is_configured() ) {
        return null; // fall through to Benecaster's own query
    }
    return my_elasticsearch_search( $q, $show_id, $tiers, $page, $per_page );
}, 10, 6 );

Notes

The returned result array shape is required: each item must include episode_id, title, excerpt, tier_slug, episode_type, and permalink. benecaster_search_results fires regardless of whether results came from Benecaster's own query or this short-circuit.

Affects

GET /benecaster/v1/search REST endpoint
benecaster_search shortcode

Need this built rather than just documented? See our services →