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.
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.
Public Functions — A stable function API for reading Benecaster data from your own code. Use benecaster_get_feed_url(), benecaster_get_user_tier(), 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 core 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.
Free Vs Premium Hooks
Free hooks are always registered, regardless of license status. Premium hooks are only registered when a valid paid license is active. 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) require a paid license
- Calling
add_filter()oradd_action()on a premium hook on a free install has no effect — the hook is never fired
Each hook’s documentation notes whether it is free or premium.
To check license status in your own code: benecaster_is_premium() returns true if a valid license is active.
Naming Conventions
All public hooks and functions use the benecaster_ prefix.
| Type | Pattern | Example |
|---|---|---|
| Actions | benecaster_{noun}_{verb} |
benecaster_token_generated |
| Filters | benecaster_{noun} or benecaster_{noun}_{context} |
benecaster_feed_episodes |
| Functions | benecaster_{verb}_{noun}() |
benecaster_get_feed_url() |
| Shortcodes | [benecaster_{noun}] |
[benecaster_player] |
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.
Building from Source
If you’re building Benecaster from source (contributing or developing an add-on against the development branch), you’ll need to run Composer after updating:
composer install
Production dependencies bundled with the plugin (committed to vendor/):
| Package | Version | Purpose |
|---|---|---|
openspout/openspout |
^4.28 |
Multi-sheet XLSX generation for the Settings → Your Data export feature (added feature/data-export) |
The vendor/ directory is committed — end users installing from a release zip do not need Composer. Only developers pulling the repository directly need to run composer install after a pull that adds new dependencies.
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.
If you’re building on Benecaster for clients or distributing code publicly, subscribe to release notes to catch deprecation notices early.
