Skip to main content

benecaster_member_thanks_query_types

Filter Premium

Filters the registered query strategies available to the [benecaster_member_thanks] shortcode and — when the Podcast Workflow add-on is active — to the Member Thanks tile in the Episode Workbench. The array is keyed by type slug; each value is a plain array with a label, a description and a results callable. There is no interface to implement and no class name to know.

label is the display name in the selector dropdown and description is the helper text below it. results receives ( int $show_id, int $episode_id, array $args ) and returns a list of rows carrying at least user_id, display_name, tier_slug and joined_at (anniversary_label optional). Honour count and tier_slug from $args when they are set. Built-in type slugs are new_since_last_episode, random, random_cycling and milestone.

Parameters

Name Type Default Description
$types array — Keyed array of strategy definitions: slug => [ 'label' => string, 'description' => string, 'results' => callable ].

Returns: array

Example

add_filter( 'benecaster_member_thanks_query_types', function ( array $types ): array {
    $types['top_supporters'] = [
        'label'       => __( 'Top supporters', 'my-addon' ),
        'description' => __( 'Members with the highest lifetime support.', 'my-addon' ),
        'results'     => function ( int $show_id, int $episode_id, array $args ): array {
            return my_get_top_supporters(
                $show_id,
                $args['count'] ?? 5,
                $args['tier_slug'] ?? null
            );
        },
    ];

    return $types;
} );

Notes

Only members who chose to be listed publicly are ever named: Benecaster drops every row whose member has not ticked the Supporter Wall's public-listing option, and every row with no user_id, from whatever results returns, before the shortcode or the REST endpoint sees it. Apply the same condition in your own query (SupporterWallManager::META_KEY_SUBSCRIBER_VISIBLE = '1' in user meta), or a list asked for count rows comes back short. See Register a custom Member Thanks query type.

Custom types added via this filter appear automatically in the Episode Workbench tile's query selector dropdown — no Workbench code changes are needed. Do not reuse a built-in slug (new_since_last_episode, random, random_cycling, milestone) as your own key.

results receives ( int $show_id, int $episode_id, array $args ) — show first. The sibling filter benecaster_related_episodes_query_types takes the same two IDs in the opposite order, and both are integers, so PHP will not catch a transposition.

An entry whose results is missing or not callable is silently discarded, not fataled — a type that never appears in the dropdown is usually a malformed definition rather than a registration failure.

A strategy that throws shows nothing, and no other type stands in. Any exception or error from results is caught, written to Settings → Tools → Debug Log once per type per request, and counted as finding nobody: [benecaster_member_thanks] prints nothing and GET /episodes/{id}/member-thanks returns an empty list. Unlike benecaster_related_episodes_query_types, there is no fallback type, because a fallback would thank a list the podcaster did not choose. A failing strategy therefore looks exactly like one that found nobody to thank; the Debug Log is where to tell the two apart.

random and random_cycling are deliberately separate strategies, not a duplicate. random is a plain random draw with no memory; random_cycling (Podcast Workflow add-on) works through the whole subscriber list before anyone repeats. Without that add-on, random_cycling behaves like random — the separate slug exists so a podcaster can state which they meant, rather than having the meaning change when an add-on is activated.

Affects

Related Recipes

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