Skip to main content

Register a community platform, and know when the add-on calls it

Premium Advanced Community Integrations

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_platforms filter is applied once, the first time the add-on’s CommunityPlatformRegistry is read, so a platform added from a benecaster_boot callback 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’s getSlug(); an entry added without a key ($platforms[] = …) is filed under getSlug(). 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 from getSlug(), a bad slug, a constructor or getSlug() 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 ) returns true; a throw from isConfigured() counts as false, so one platform’s bug never stops the others. addMember(), a move to a higher tier (or between tiers that can’t be ranked) and onEpisodePublished() 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 except removeMember() (and isConfigured() 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_tier and $new_tier are 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, and isConfigured( $show_id ) is asked first as usual. So removeMember() and isConfigured() 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 the plugins_loaded example below does.
  • The built-in platforms are registered on the same filter, as circle and discord. 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'];
}

View on GitHub →

Hooks Used

  • benecaster_community_platforms

Need this built rather than just documented? See our services →