`benecaster_explicit_badge_mode`

Filter Free

Overrides the resolved explicit mode for one episode before the badge is rendered. This is the first of the three badge filters to run, and the value it returns is what benecaster_explicit_badge_label and benecaster_explicit_badge_html then see.

The incoming mode has already been resolved: the episode’s own override wins, and an episode set to inherit falls back to the show’s setting. Filter here when you want to change that outcome programmatically without writing to the episode — a special series that should carry the badge regardless, a syndication context where everything renders clean, a rule driven by category rather than by the stored value.

Change the mode, not the wording. If what you want is different text, use the label filter. The mode is the semantic value and it drives the aria-label and the class modifiers as well as the visible text.

This is the show-side enum, not the episode-side one. It is 'clean', 'yes', or 'explicit' — the three values the show’s Explicit selector offers. It is not the episode override enum ('inherit' / 'yes' / 'no'), because by the time the badge renders, inheritance has already been resolved and there is nothing left to inherit. A return value outside the three legal modes falls back to 'clean', which renders nothing — failing toward silence rather than toward a wrong label on somebody’s episode.

Restyle or reword the Explicit badge

Free Beginner

The Explicit badge is rendered by one class — Benecaster\Episode\ExplicitBadgeRenderer — from every surface it appears on: the episode single page, archive cards, the [benecaster_episodes] list, the [benecaster_player] title strip, and the [benecaster_explicit_badge] shortcode. All of them share the same three filters, so a single hook changes the badge everywhere rather than needing a template override per surface.

Three asks come up repeatedly, and each maps to exactly one filter. Pick the smallest one that does the job.

“Change the wording.” Use the label filter. “E”, “18+”, “Adult”, your own phrasing — all one line, and the accessibility attributes and class modifiers stay intact.

“Restyle it.” Usually no PHP at all. The markup already carries --{mode} and --context-{surface} class modifiers, so CSS can style explicit differently from clean, and the archive grid differently from the single page. Reach for the HTML filter only when you need to change the structure — injecting an icon, say — not the appearance.

“Force it on for this one episode.” Use the mode filter. It overrides the resolved value without writing to the episode, which keeps a one-off out of your stored data.

<?php
// 1. Replace "Explicit" with a short "E" everywhere the badge renders.
add_filter( 'benecaster_explicit_badge_label', function ( string $label, string $mode ): string {
    return 'clean' === $mode ? $label : 'E';
}, 10, 2 );

// 2. Restyle without touching templates — the class list already carries
//    two modifiers (--{mode} + --context-{surface}), so plain CSS handles
//    most cases. The HTML filter is the escape hatch when class-only styling
//    is not enough (e.g. injecting an <svg> icon for aria-hidden purposes).
add_filter( 'benecaster_explicit_badge_html', function ( string $html, int $episode_id, int $show_id, string $mode, string $context ): string {
    if ( 'clean' === $mode ) {
        return $html; // leave the empty string alone
    }
    return sprintf(
        '<span class="my-explicit" role="img" aria-label="%s"><svg aria-hidden="true"></svg><span class="visually-hidden">%s</span></span>',
        esc_attr__( 'Explicit content', 'my-theme' ),
        esc_html__( 'Explicit', 'my-theme' )
    );
}, 10, 5 );

// 3. Force the badge on a specific episode without touching the stored
//    meta — useful for a one-off override during a special series.
add_filter( 'benecaster_explicit_badge_mode', function ( string $mode, int $episode_id, int $show_id ): string {
    return 12345 === $episode_id ? 'yes' : $mode;
}, 10, 3 );

View on GitHub →

Parameters

Name	Type	Default	Description
`$mode`	`string`	—	Resolved mode — `'clean'`, `'yes'`, or `'explicit'`. Both `'yes'` and `'explicit'` mean explicit; the difference is only the podcaster's chosen wording.
`$episode_id`	`int`	—	WordPress post ID of the episode being rendered.
`$show_id`	`int`	—	WordPress post ID of the episode's show.

Returns: string

Examples

Force the badge on a single episode

add_filter( 'benecaster_explicit_badge_mode', function ( string $mode, int $episode_id, int $show_id ): string {
    return 12345 === $episode_id ? 'yes' : $mode;
}, 10, 3 );

Suppress every badge on one show

add_filter( 'benecaster_explicit_badge_mode', function ( string $mode, int $episode_id, int $show_id ): string {
    // Show 88 is syndicated to a partner that renders its own rating chip.
    return 88 === $show_id ? 'clean' : $mode;
}, 10, 3 );