Skip to main content

benecaster_related_episodes

Filter Free

Filters the resolved related episode list after the configured query strategy returns its results, before any rendering takes place. Use to add, remove, or reorder episodes in the list — for example, always pin a specific episode first, exclude episodes from a specific season, or deduplicate the result set.

Applies to both the benecaster_related_episodes shortcode and the Related Episodes Episode Page block, which renders through the shortcode’s pipeline. The block’s query type is the one chosen in its Which episodes to list setting, latest by default. The list arrives after the latest fallback has run: when the chosen type found nothing, you receive the latest episodes.

Parameters

Name Type Default Description
$episodes WP_Post[] — Array of episode WP_Post objects returned by the query type
$episode_id int — Source episode ID for the relationship query
$show_id int — ID of the show
$args array — The query arguments: `count` (int) and `exclude_current` (bool)

Returns: WP_Post[]

Examples

Pin a featured episode first in the related list

add_filter( 'benecaster_related_episodes', function ( $episodes, $episode_id, $show_id, $args ) {
    $pinned_id = (int) get_post_meta( $show_id, '_show_pinned_related_episode_id', true );
    if ( $pinned_id ) {
        $pinned = get_post( $pinned_id );
        if ( $pinned ) {
            array_unshift( $episodes, $pinned );
        }
    }
    return $episodes;
}, 10, 4 );

Exclude episodes from season 1

add_filter( 'benecaster_related_episodes', function ( array $episodes, int $episode_id, int $show_id, array $args ): array {
    return array_filter( $episodes, function ( $episode ) {
        return get_post_meta( $episode->ID, '_benecaster_season', true ) !== '1';
    } );
}, 10, 4 );

Affects

Related Recipes

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