`benecaster_latest_episode_id`

Filter Free Since v1.0.0

Filters the resolved episode ID before [benecaster_latest_episode] renders or benecaster_get_latest_episode_id() returns. Use to pin a specific episode as the perpetual latest — for example a permanently featured episode — or to override the resolution logic for shows with complex publishing schedules. Return null to suppress rendering entirely.

This filter fires in both the [benecaster_latest_episode] shortcode and the benecaster_get_latest_episode_id() helper function. When null is returned, the shortcode outputs nothing and benecaster_latest_episode_output does not fire.

Parameters

Name	Type	Default	Description
`$episode_id`	`int\|null`	—	ID of the resolved latest episode, or null if no episodes are published
`$show_id`	`int`	—	ID of the show

Returns: int|null

Examples

Pin featured episode from show meta

add_filter( 'benecaster_latest_episode_id', function( $episode_id, $show_id ) {
    $pinned = (int) get_post_meta( $show_id, '_show_featured_episode_id', true );
    if ( $pinned && get_post_status( $pinned ) === 'publish' ) {
        return $pinned;
    }
    return $episode_id;
}, 10, 2 );

Pin specific episode for one show

add_filter( 'benecaster_latest_episode_id', function( ?int $episode_id, int $show_id ): ?int {
    if ( $show_id === 42 ) {
        return 1234; // always show episode 1234 for this show
    }
    return $episode_id;
}, 10, 2 );

Suppress shortcode when no episodes exist

add_filter( 'benecaster_latest_episode_id', function( ?int $episode_id, int $show_id ): ?int {
    if ( null === $episode_id ) {
        return null; // suppresses shortcode output
    }
    return $episode_id;
}, 10, 2 );

Notes

Returning null suppresses the shortcode entirely — no HTML is output and benecaster_latest_episode_output does not fire.

Affects

[benecaster_latest_episode] shortcode
benecaster_get_latest_episode_id() function