benecaster_episode_references
Filters the references array for an episode before it is included in the REST response. This filter runs on read, not on write — it does not affect what is stored in the database, only what is returned to the episode editor and templates.
You can inject additional keys onto any reference object, remove references from the response, reorder them, or inject entirely synthetic entries with string-based `id` values. Add-ons that augment references should note that the filter may fire more than once per episode editor load — once when the full episode response is fetched, and once when the references endpoint is called directly.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$references |
array |
— | Array of reference objects {id, reference_id, label, url, description, display_label, group_id, display_order} |
$episode_id |
int |
— | ID of the episode |
$show_id |
int |
— | ID of the show |
Returns:
array
Examples
Inject synthetic affiliate reference
add_filter( 'benecaster_episode_references', function( $references, $episode_id, $show_id ) {
$affiliate_url = 'https://myaffiliate.example.com/?ep=' . $episode_id;
$references[] = [
'id' => 'affiliate-' . $episode_id,
'reference_id' => 0,
'label' => 'Affiliate Partner',
'url' => $affiliate_url,
'description' => '',
'display_label' => 'Affiliate Partner',
'group_id' => null,
'display_order' => 99,
];
return $references;
}, 10, 3 );
Attach tracked redirect URL to each reference
add_filter( 'benecaster_episode_references', function( array $references, int $episode_id, int $show_id ): array {
return array_map( function( array $ref ) use ( $episode_id ): array {
$tracked_url = get_post_meta( $episode_id, '_outlinks_tracked_' . $ref['id'], true );
if ( $tracked_url ) {
$ref['tracked_url'] = $tracked_url;
}
return $ref;
}, $references );
}, 10, 3 );
Exclude references by group
add_filter( 'benecaster_episode_references', function( array $references, int $episode_id, int $show_id ): array {
return array_values( array_filter( $references, function( array $ref ): bool {
return $ref['group_id'] !== 42; // Exclude internal-only group.
} ) );
}, 10, 3 );
Notes
This filter fires on read, not on write — it does not affect what is stored in the database. The primary use case is an add-on that attaches externally managed data to reference entries (for example, a per-episode tracked redirect URL) without modifying the stored url field. The filter may fire more than once per episode editor load.
