For Developers

Benecaster is built hook-first. Every significant action fires a do_action hook. Every significant output passes through apply_filters. No output is printed without being filterable, and no action is taken without hooks before and after it.

This section documents the public developer API: actions, filters, public functions, classes, shortcodes, and recipes. Everything here is intentionally stable — these are the extension points that third-party code can depend on across versions.

What’s Available

Actions — Hooks that fire at significant moments in Benecaster’s lifecycle. Use them to trigger your own code when something happens: a subscriber token is generated, an episode is published, a subscription is cancelled.

See Action Hooks Reference.

Filters — Hooks that let you modify data before Benecaster uses it. Use them to change feed output, customize episode data, control visibility, or modify email content.

See Filter Hooks Reference.

Public Functions — A stable function API for reading Benecaster data from your own code. Use benecaster_get_feed_url(), benecaster_get_user_tier_for_show(), and similar functions rather than querying the database directly. The function signatures are versioned; direct database queries are not.

See Public Functions Reference.

Classes — Public PHP classes and interfaces that your code can extend or implement. The most important is BridgeInterface — the interface you implement to build a bridge for a membership plugin that isn’t in the built-in bridge set.

See Classes Reference.

Shortcodes — All Benecaster shortcodes as an API surface: full attribute tables, available filters per shortcode, and extension points. For usage documentation (how to place shortcodes in pages and posts), see the Shortcodes Reference in the Blocks & Widgets section.

See Shortcodes Developer Reference.

Recipes — Standalone implementation guides combining hooks, filters, and functions to accomplish specific real-world tasks. Each recipe is a complete, copy-paste-ready starting point.

See Developer Recipes.

WP-CLI — Benecaster exposes a WP-CLI command for clearing the feed cache — useful in CI/CD pipelines, batch import scripts, and situations where the admin UI isn’t accessible.

See WP-CLI: Cache Clear.

Free Vs Premium Hooks

Hooks are not a paid feature — none of them is gated behind a purchase. Free hooks fire on any install. Premium hooks sit on code paths that only run on a licensed install, so on an unlicensed site they simply never fire; there is nothing for them to act on. This means:

• Free tier installs and unlicensed installs have access to all free hooks
• Premium hooks (token lifecycle, subscription events, visibility filters, most analytics hooks) only fire on installs with a paid license
• Calling add_filter() or add_action() on a premium hook on a free install has no effect — the hook never fires

Each hook’s documentation notes whether it is free or premium.

To check license status in your own code: benecaster_is_premium( $show_context ) returns true if the given show has a valid license active. When no show is in scope, use benecaster_any_show_is_premium() instead.

Naming Conventions

All public hooks and functions use the benecaster_ prefix.

Template Overrides

Benecaster locates templates using benecaster_locate_template(), which checks your theme directory before falling back to plugin templates. To override any template, copy it from the plugin’s templates/ directory to a benecaster/ directory in your theme and modify it there.

Template override path: {your-theme}/benecaster/{template-path}

Use benecaster_get_template_part() in custom code to load templates with theme override support automatically.

A Note on Internal Code

Only the items documented in this section are considered public API. Internal classes, functions, and hooks not listed here may change between versions without notice. Don’t build against undocumented internals — they’re not covered by the deprecation policy.

Deprecation Policy

When a public hook or function is deprecated, it receives a _deprecated_hook() or _deprecated_function() notice for one major version before removal. Deprecations are listed in the changelog and in a dedicated deprecation log on this site.

For a security or stability issue, removal may happen sooner than one major version. The deprecation notice and changelog/deprecation-log entries still apply — only the timeline is compressed.

If you’re building on Benecaster for clients or distributing code publicly, subscribe to the release feed to catch deprecation notices early.