benecaster_search_supplemental_episode_ids
Allows add-ons to inject additional episode IDs into the Benecaster’s own search result set before pagination. Benecaster merges them into the query it was already running, so result counts and page numbers stay correct — you do not have to reconcile totals yourself.
This is a Free filter, and one of three that shape search: use benecaster_search_indexable to control which episodes are searchable at all, benecaster_search_query_args to adjust Benecaster’s own query, and this one to add results Benecaster’s own query could never have found. Use it when your add-on stores searchable content outside the Benecaster episode records — for example, an add-on that indexes chapter titles or guest notes in a table of its own can return matching episode IDs here. Transcripts are already covered: the Transcription Service add-on hooks this filter itself, adding the episodes whose transcript matches only for searchers its visibility setting allows, and never for a transcript set to Hidden. Callers are responsible for their own visibility and tier gating before returning IDs — only return episode IDs the requesting user should be able to see. Benecaster automatically strips duplicates and IDs of 0 or less.
Gate a buy-up’s content on $holdings, not on $tiers. $holdings is everything the searcher holds on the show, resolved exactly as their feed is: their tier slug, then any buy-up and standalone grant slugs, with public as the base for a follower or a listener over the show’s limit. $tiers is the list the search query filters by — normally the same slugs, but ['public'] for a member who holds nothing, and whatever a benecaster_search_query_args callback narrowed it to; that filter does not change $holdings. $holdings can be empty: a lapsed member who owns nothing, the same listener whose feed is refused. Treat empty as “holds nothing”.
Who the searcher is. A request sent with Authorization: Bearer and a feed token for this show is that token’s holder — $user_id is the token’s owner even though nobody is logged in (a podcast app or a headless site). Otherwise it is the logged-in user, whose holdings come from their active feed on the show. A logged-in user with no active feed on the show gets $holdings of ['public'] with their user ID; an anonymous visitor gets ['public'] and 0. Both routes resolve holdings the way the feed does, so search can never grant what the feed would not.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$ids |
int[] |
— | Starts empty; add episode post IDs to include in the result set |
$term |
string |
— | Search term |
$show_id |
int |
— | Show post ID |
$tiers |
string[] |
— | The slugs the search query filters by — tier, buy-up and grant — or `['public']` |
$holdings |
string[] |
— | Everything the searcher holds on this show — tier, buy-up and grant slugs, resolved as their feed is. Empty when they hold nothing. Gate buy-up content on this. |
$user_id |
int |
— | The searcher — a Bearer feed token's owner, else the logged-in user — or `0` for an anonymous visitor |
Returns:
int[]
Examples
Inject episode IDs from your add-on's own index
add_filter( 'benecaster_search_supplemental_episode_ids', function( array $ids, string $term, int $show_id, array $tiers, array $holdings, int $user_id ): array {
// Search your own guest notes, only for what this listener actually holds.
$matches = my_addon_search_guest_notes( $term, $show_id, $holdings );
return array_merge( $ids, $matches );
}, 10, 6 );Notes
Callers must handle their own visibility and tier gating before returning IDs — only return episode IDs the requesting user should be able to see. Benecaster strips duplicates and IDs of 0 or less from the returned array automatically. See also: benecaster_search_indexable to exclude individual episodes from results after SQL, and benecaster_search_query_args to modify query arguments before the search runs.
Affects
- GET /benecaster/v1/search REST endpoint
Need this built rather than just documented? See our services →