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.

---

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.

---

Episode Template Parts

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

$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.

---

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.

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

If you are looking for account/display-name.php or account/display-name-prompt.php, neither exists. The wall name field lives in account/avatar.php, and the prompt is account/wall-name-prompt.php, taking $wall_name_prompt_prefill. An override sitting at either of those other paths does nothing at all — silently, because a template that does not exist in the plugin is never looked for in your theme.

Upgrade note — account/buyups.php overrides break buy-up purchases

If you overrode account/buyups.php before buy-up purchase consent shipped, every buy-up purchase from your theme now fails.

The stock template emits data-buyup-amount-cents on the “Add to my plan” button, and assets/js/buyups.js reads that attribute and sends it as the required confirm_amount_cents field. An older override renders a button without the attribute, the script sends nothing, and the endpoint rejects the purchase with 400 confirm_amount_required.

Nothing in the admin, the logs or the server surfaces this as a template problem — the purchase simply does not complete. Re-sync your override against the current stock template.

The value is the price in integer minor units:

data-buyup-amount-cents="<?php echo esc_attr( (string) (int) round( (float) $buyup['price'] * 100 ) ); ?>"

See Buy-ups Subscriber REST API for what the endpoint does with it.

---

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:

// Modify the share links array without touching episode/share.php:
add_filter( 'benecaster_episode_share_links', function ( array $links, int $episode_id ): array {
    $links[] = [
        'label' => 'Copy link',
        'url'   => '#',
        'class' => 'benecaster-share-copy js-copy-link',
    ];
    return $links;
}, 10, 2 );

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

---

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. 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
• 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