Template Overrides (Developer Reference)

Benecaster renders episode pages, the episode archive, and subscriber account pages using PHP template parts. Every template part can be overridden from a child theme or parent theme — no plugin code required. Replacing a single file is enough to change any part of the output.

Looking for email templates? They use the same override mechanism but a different directory, and they’re documented separately in Customizing Email Templates — which lists every email template, the variables each one receives, and the benecaster_email_wrapper_args filter that handles branding without requiring an override at all. One difference: content an email editor add-on has stored for an email beats your theme’s override of it.

---

Override Path

Place an overriding file at:

wp-content/themes/[your-child-theme]/benecaster/[template-relative-path].php

The path mirrors the plugin’s own templates/ directory exactly. For example, to override the episode title:

Plugin default:    wp-content/plugins/benecaster/templates/episode/title.php
Your override:     wp-content/themes/my-child-theme/benecaster/episode/title.php

Resolution order: child theme → parent theme → registered add-on directories → plugin default. The first readable file found is used.

Your theme override wins over everything, add-ons included. An add-on can register its own template directory (see below), but it sits third in that list — it can replace one of Benecaster’s own defaults and it can never outrank a file you put in your theme. If you have overridden a part and it has stopped taking effect, an add-on is not the cause.

An override keeps the wording it was copied with. When Benecaster changes the text in one of its templates, a copy in your theme keeps showing the old text indefinitely, and nothing warns you. For example, the subscriber account page’s buy-up section is now headed Extras, but a copy of account/buyups.php made earlier still says Add-ons. After an update, compare your overrides with the current templates and copy across any changes you want.

---

Episode Template Parts

All episode template parts receive at minimum $episode_id (int) and $show_id (int).

episode/download.php and episode/transcript.php are included by episode/single.php, and the parts themselves do not check access. single.php includes the download link only when the episode’s download setting is on and the visitor can play the episode (the show’s Show a download link on episode pages for an episode with an audio file, Show a download link on video-only episodes for one whose only file is a video), narrowed by the benecaster_show_episode_download filter. It includes the transcript link only when the episode has a transcript URL and the visitor can access the episode, narrowed by the benecaster_show_episode_transcript filter. A theme that overrides single.php must make the same decisions itself by calling \Benecaster\Episode\EpisodePageLinkGate::shows_download() and shows_transcript() before including the parts, or the links never appear. Don’t include either part from anywhere else, because an override of it assumes the check already happened.

$user_tier is the subscriber’s internal tier slug, or an empty string when the visitor is not subscribed. $required_tier is the minimum tier required to access the episode, or an empty string when undetermined.

What the player parts play

episode/single.php and archive/episode-card.php include their player part when the benecaster_show_episode_player filter says so, and pass it $can_access: whether the visitor passed the access check, not whether that filter opened the player. The difference matters because a callback can open the player for a visitor who cannot access the episode (the preview clip does), and the clip is swapped in on the audio URL only. Nothing swaps an embed or a video, so the parts play those only when $can_access is exactly true. A player opened for anyone else plays the audio URL, or nothing.

Overriding episode/single.php? Keep its do_action( 'benecaster_after_episode_content_area', … ) line. The Transcription Service add-on prints the episode’s Transcript section there; without the line the section disappears and Benecaster’s Read the transcript link comes back in its place, under the same transcript visibility.

Overriding episode/single.php or archive/episode-card.php? Pass 'can_access' => $can_access to the player part, and in archive/episode-card.php to the excerpt part too. Without it each part treats every visitor as locked: an episode with no audio URL (an embed, or a video only) shows no player to anyone, and the card’s excerpt shows the teaser.

Overriding either player part? Apply the same check before you play an embed or a video. Print an embed code through \Benecaster\Episode\EmbedHtml::sanitize(), never wp_kses_post(): WordPress’s post allowlist has no <iframe>, so it strips the embed and leaves an empty player. EmbedHtml::sanitize() keeps an <iframe> only when it loads from an https:// address.

When a player part plays a video or an embed, it loads Benecaster’s base stylesheet, which sizes the video to its column and caps an embed’s width at it. An override of either part keeps its own markup and does not load the stylesheet; call \Benecaster\Shortcodes\ShortcodeBaseStyles::enqueue() from it, or size the video in your theme. See Styling the Shortcodes.

---

Archive Template Parts

All archive template parts receive at minimum $show_id (int).

---

Show Page Template Parts

All show page template parts receive $show_id (int).

---

Global Template Parts

Locked state templates receive at minimum $episode_id (int) and $show_id (int).

---

Account Template Parts

Most account template parts receive $show_id (int) and $user_id (int). The wall name prompt receives $user_id only — the wall name is not show-scoped.

$sub['feed_url'] is null whenever the URL cannot be recovered — a token created before encrypted copies were stored, a changed or missing encryption key, a host without libsodium — and always when the feed is dark. Treat null as ordinary and fall back to $masked_url; never build a URL from anything else. An override that drops the data-feed-url or data-qr-value attribute silently disables Copy, the QR code and the app buttons. Because these three templates render the working URL, an override must only ever be shown to the subscriber who owns it. An override of feed-url.php, qr-code.php or app-links.php copied from an older version of Benecaster keeps showing the masked URL and disabled buttons until you copy the current template again.

Overriding the Buy-ups and Billing Period Templates

These two templates carry the price a subscriber agrees to, not just the price they see. Each button echoes an amount back to the server, and the server refuses the request if it doesn’t match what it would charge. An override that shows the wrong figure therefore breaks the action, not just the display. Copy both from the current built-in template, and re-copy them when the plugin changes them.

account/buyups.php. Each $buyups row describes the price that matches this subscriber’s billing period: price (major units, and nullable), amount_cents, currency, interval_unit and interval_count. A null price means the buy-up isn’t sold on their period. Never treat it as 0, because 0 is a real price (a buy-up included free). The Add to my plan button must carry data-buyup-amount-cents from that row’s amount_cents. An override written before per-period pricing shows everyone the buy-up’s default (monthly) price, and every purchase through it fails with 409 amount_mismatch. Nothing server-side points at the template as the cause.

The plan and billing-period sections share one pending change. Only the section that owns the pending change shows it with a Cancel this change button; the other points at it. Two override traps follow, and both look like the feature failing rather than an old copy:

• An override of account/dashboard.php made before the plan section existed doesn’t include it, so subscribers see no Your Plan section at all.
• An override of account/cadence-switch.php made before the plan section existed renders its own pending block, so a pending plan move shows a second, working Cancel this change button.

Refresh both from the current built-in templates.

account/cadence-switch.php. Each option’s amount_formatted is the tier price alone. When the subscriber holds buy-ups, the option also carries buyups, buyups_amount_cents, total_formatted, buyups_included and buyups_dropped, and the Switch to… button must carry data-buyups-amount-cents. An override without it can’t switch a subscriber who pays for a buy-up (400 confirm_amount_required), and one that omits the included and lost lines lets a subscriber lose a free buy-up without being told. See The Subscriber Account Page.

account/tier-switch.php. Each option in tier_options carries lands: now for an upgrade, which is charged the day the subscriber asks, and renewal for everything else. The template prints a different line for each — “Starts today. You pay the difference for the rest of this billing period now…” or “Starts {date}, at your next renewal. Nothing is charged today.” — and lists buyups_ending, the paid buy-ups the new plan doesn’t offer, which end at the end of the current period. When pending.awaiting_payment is true, an upgrade is waiting for the subscriber’s bank, and the pending block says so and gives the Cancel this change button a data-awaiting-payment attribute. An override made before upgrades took effect straight away prints the renewal line under an upgrade that is charged today, and leaves out the ending buy-ups. The charge itself is still right — the amount comes from a price check the plugin’s script runs when the button is clicked, and the confirmation box shows it before anything is taken — but the page contradicts it. Re-copy the template. See A Subscriber Was Charged When the Page Said Nothing Would Be Charged Today.

account/avatar.php and account/dashboard.php are overridable the same way and have their own pages — see Account Avatar Template.

---

Template Functions

Each of these has a full reference entry in the function library — signature, parameters, return values, and examples.

benecaster_get_template_part( $template, $vars = [], $echo = true )

Load a template part with child theme → parent theme → registered add-on directories → plugin default resolution.

// Load and echo a template part (typical usage in another template):
benecaster_get_template_part( 'episode/title', [
    'episode_id' => $episode_id,
    'show_id'    => $show_id,
] );

// Load and return the rendered HTML:
$html = benecaster_get_template_part( 'episode/title', [
    'episode_id' => $episode_id,
    'show_id'    => $show_id,
], false );

Variables in $vars are extracted into the template’s local scope — $vars['episode_id'] becomes $episode_id inside the template file.

---

benecaster_locate_template( $template )

Check whether a theme override exists for a template part. Returns the absolute path of the override file if found, or false if the plugin default will be used.

$override = benecaster_locate_template( 'episode/title' );
if ( $override ) {
    // A theme file is overriding this template part.
}

This searches the child theme and parent theme only. It deliberately does not see registered add-on directories — an add-on directory is not a theme override, and this function answers the theme question. For “which file would actually load?”, use benecaster_get_template_path() below.

---

benecaster_get_template_path( $template )

Return the full path of the file that would be loaded — theme override, registered add-on directory, or plugin default. Returns an empty string when no file exists at any of the four locations.

$path = benecaster_get_template_path( 'episode/title' );
// '/var/www/html/wp-content/themes/my-child-theme/benecaster/episode/title.php'
// or the plugin's own default path if no theme override exists.

---

benecaster_register_template_directory( $path )

For add-on authors. Registers a directory that Benecaster will search when resolving template parts, so an add-on can ship its own parts — both ones that replace a Benecaster default and ones Benecaster has never heard of. Call it from a benecaster_boot callback.

add_action( 'benecaster_boot', function (): void {
    benecaster_register_template_directory( plugin_dir_path( __FILE__ ) . 'templates' );
} );

The directory mirrors the plugin’s templates/ structure, so {$path}/guest/profile-card.php answers the template name guest/profile-card.

Registered directories sit third, behind both themes. A part shipped by an add-on is still fully overridable from your theme at {theme}/benecaster/guest/profile-card.php — registration does not change that, and add-on authors should treat any part they ship as a public template.

Among add-ons the order is registration order, which is add-on boot order — so two add-ons registering the same template name is not a supported arrangement.

---

benecaster_get_header( $name = null )

Load the site header in a way that is compatible with both classic and block (FSE) themes. Use this in outer template files (single.php, archive.php) instead of calling get_header() directly.

• On block themes: renders the header block template part via block_template_part( 'header' ).
• On classic themes with header.php: calls get_header( $name ) normally.
• On themes without a header file: degrades silently — no output, no deprecation notice in the log.

Eliminating the deprecation log spam from FSE themes was the primary reason this helper was added. If you are overriding templates/episode/single.php, templates/show/single.php, or templates/archive/archive.php in your theme, replace any get_header() call with benecaster_get_header().

<?php benecaster_get_header(); ?>

<main class="benecaster-episode-single">
    <?php benecaster_get_template_part( 'episode/title', [ 'episode_id' => $episode_id ] ); ?>
    <?php // ... ?>
</main>

<?php benecaster_get_footer(); ?>

---

benecaster_get_footer( $name = null )

Counterpart to benecaster_get_header(). Use in outer template files instead of get_footer().

• On block themes: renders the footer block template part via block_template_part( 'footer' ).
• On classic themes with footer.php: calls get_footer( $name ) normally.
• On themes without a footer file: degrades silently.

---

Two Customization Layers

Template overrides replace whole files. When you only need to change a value, tweak markup, or inject content without replacing a template, use the complementary hook layers instead:

Before/after action hooks fire around every rendered section:

// Inject content before the episode navigation without overriding navigation.php:
add_action( 'benecaster_before_episode_navigation', function ( int $episode_id, int $show_id ): void {
    echo '<hr class="my-divider">';
}, 10, 2 );

Output filters intercept specific values before they reach the template:

// Add a Bluesky link to episode/share.php without overriding it:
add_filter( 'benecaster_episode_share_links', function ( array $links, int $episode_id ): array {
    $links['bluesky'] = [
        'label' => 'Share on Bluesky',
        'url'   => 'https://bsky.app/intent/compose?text=' . rawurlencode( get_permalink( $episode_id ) ),
        'class' => 'benecaster-share-bluesky',
    ];
    return $links;
}, 10, 2 );

See Filter Hooks Reference and Action Hooks Reference for the full catalog.

---

Styling the Shortcodes

Benecaster ships a base stylesheet for its front-end shortcodes — the player, episode lists, latest-episode card, pricing table, episode navigation, related episodes, and the share, social, platform and RSS links. It loads only on a page where one of them appears, or where the episode page or an archive card plays a video or an embed (the stylesheet fits the video to its column; audio needs none). If your site already styles these shortcodes, expect them to look a little different after updating, and check them once.

Adjust it. Every rule has zero specificity, so a plain class selector in your theme always wins. The common knobs are CSS custom properties:

:root {
    --benecaster-gap: 1.5rem;
    --benecaster-radius: 0;
    --benecaster-border: 1px solid #ddd;
    --benecaster-icon-size: 2rem;
    --benecaster-card-min: 16rem;
}

Turn it off. For a theme that styles the shortcodes itself, add this to functions.php or a plugin:

add_filter( 'benecaster_shortcode_base_styles', '__return_false' );

wp_dequeue_style() does not work for this stylesheet: the shortcodes load it while the page is rendering, after a theme’s dequeue has already run. Use the benecaster_shortcode_base_styles filter instead. It is read once, on init, so it cannot go inside a template. Turning it off also removes it from block editor and Elementor previews, so the editor matches the front end.

Use your own icons. The icon styles of the social, platform, share and RSS link shortcodes draw a built-in icon for every platform. To draw your theme’s icons instead, use the benecaster_platform_icon_svg filter — see the recipe Use your own icon set for social, platform and share links.

---

Templates Management REST Endpoints

The Settings → Templates screen is backed by four REST endpoints. Use these for headless setups, add-ons that bundle a custom template, or custom admin UI.

All endpoints require manage_options capability and a valid WP REST nonce. POST /benecaster/v1/templates/upload also needs the install_plugins capability, on a site where installing code from the admin is allowed (DISALLOW_FILE_MODS not set), because a template runs PHP on your site. Otherwise it answers 403 benecaster_template_upload_forbidden with the reason. GET /benecaster/v1/templates reports whether the current user may upload as can_upload, with the reason in upload_blocked_reason when they may not. Built-in templates (Default Light, Default Dark) are always present and cannot be deleted.

---

Recipes

Worked examples for the patterns on this page live in the recipe library, each with runnable code you can copy:

• Override a single episode template part from a child theme
• Load a custom template part from an add-on
• Check episode access in a shortcode or widget
• Replace the episode share links with a custom share card
• Inject a “Listen now” CTA button into every archive episode card
• Hide the sort controls on the episode archive
• Turn off, or restyle, Benecaster’s base styles for its shortcodes
• Use your own icon set for social, platform and share links
• Customize the upgrade prompt for a specific show
• Add a custom section to the show page
• Add a custom section below the QR code on the subscriber account page