Register a community platform, and know when the add-on calls it
How the Community Integrations add-on finds your platform and when it calls each method of CommunityPlatformInterface. For the platform class itself, see Integrate a community platform not in the Benecaster set.
- Registering. The
benecaster_community_platformsfilter is applied once, the first time the add-on’s CommunityPlatformRegistry is read, so a platform added from abenecaster_bootcallback is attached. Each entry is an object implementing the interface, or the name of such a class with a no-argument constructor. The key must equal the platform’sgetSlug(); an entry added without a key ($platforms[] = …) is filed undergetSlug(). A slug is lowercase letters, digits,-and_, starting with a letter or digit. Anything else (an array, a class that doesn’t implement the interface, a key that differs fromgetSlug(), a bad slug, a constructor orgetSlug()that throws) is dropped with a_doing_it_wrong()notice, never a fatal error. - Which shows a platform is called for. Only shows where
isConfigured( $show_id )returnstrue; a throw fromisConfigured()counts asfalse, so one platform’s bug never stops the others.addMember(), a move to a higher tier (or between tiers that can’t be ranked) andonEpisodePublished()come only for a show where the add-on is switched on.removeMember()and a move to a lower tier also come for a show where it is switched off, while the add-on still runs for another show: don’t assume the switch is on inside those two. Switching a show off calls nothing; switching it back on resyncs every member of the show. With the add-on off on every show, or its license lapsed, nothing is called exceptremoveMember()(andisConfigured()before it) for an erasure, below. - How it is called. Never once per Benecaster event and never in the request that caused it: a background job reads the member’s tier on the show when it runs, compares it with what your platform was last told, and makes the one call that closes the gap. Every member method must be safe to repeat.
$tier_slug,$old_tierand$new_tierare always base tiers of that show: a buy-up’s token, a follower, or a member whose membership can’t be confirmed never reaches you. - Failures. Return
false, or throw, and that member and show are retried for your platform alone after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then marked failed until the member’s next access change or a resync. A thrown exception’s message is stored and shown to the podcaster on the show’s Community tab beside the member’s name: write it for them, and never put a credential, token or request body in it. - Erasure. When Benecaster deletes a subscriber’s data (Delete Subscriber Data, a deleted WordPress account, the data retention sweep, or WordPress’s Erase Personal Data),
removeMember()is called for every show your platform holds them on, whatever their membership says. This runs whether or not the add-on started on that request: while it is switched off for every show, or its license has lapsed, the erasure still reaches every platform that holds the person, andisConfigured( $show_id )is asked first as usual. SoremoveMember()andisConfigured()must work on their own: read your settings and credentials directly, never through a route or a service that exists only once Community Integrations has started. No other method is called on such a request. Register your platform from code that runs either way, as theplugins_loadedexample below does. - The built-in platforms are registered on the same filter, as
circleanddiscord. A platform of your own must not reuse either slug.
Code
<?php
// Register only where the add-on (and so the interface) is loaded.
add_action( 'plugins_loaded', function (): void {
if ( interface_exists( \Benecaster\Community\CommunityPlatformInterface::class ) ) {
require __DIR__ . '/class-my-platform.php'; // class My_Platform implements the interface
add_filter( 'benecaster_community_platforms', fn( array $p ): array => $p + [ 'my-platform' => new My_Platform() ] );
}
} );
// Inside My_Platform: a failure message the podcaster can act on, no secrets.
public function addMember( int $user_id, int $show_id, string $tier_slug ): bool {
$response = my_platform_api_add( $show_id, $user_id, $tier_slug );
if ( 403 === $response['status'] ) {
throw new \RuntimeException( 'My Platform refused: the API key for this show cannot add members.' );
}
return 200 === $response['status'];
}
Hooks Used
-
benecaster_community_platforms
Need this built rather than just documented? See our services →