Skip to main content

CommunityPlatformInterface

Benecaster\Community\CommunityPlatformInterface

Interface Premium community-integrations

The interface a community platform integration must implement to join the Community Integrations add-on. Register your instance through the benecaster_community_platforms filter, keyed by platform slug.

This registration passes an object rather than an array of callbacks, and that is a deliberate exception. Benecaster’s two query-strategy registries take a label and one callable, because a strategy is a single question with a single answer. A community platform is a lifecycle contract — credentials that may not be present, three subscription methods that must agree with one another, and a separate episode-publish path — so it registers the way payment gateways do.

Once registered, the add-on keeps your platform in step with each member’s tier the same way it keeps the built-in Discord and Circle integrations in step — joins, tier changes, removals and episode publishes all arrive without being wired individually, one show at a time and from a background job. That is the point of implementing the interface rather than listening to the hooks yourself: Benecaster has many ways for access to change, and the add-on reads the member’s state after each one, so you get the whole lifecycle and stay in step with it as it grows.

Every method but getSlug() takes the show, because tiers, credentials and community settings belong to a show. When each method is called, including which ones can arrive for a show where the add-on is switched off, is in Register a community platform, and know when the add-on calls it.

Methods

Method Visibility Since Description
getSlug(): string Public — Returns a unique identifier for this platform. Used as the registry key and in stored settings, so treat it as permanent — changing it orphans existing configuration.
isConfigured( int $show_id ): bool Public — Returns whether the podcaster has finished setting the platform up for this show — typically whether that show's API key is present. Return false and the platform is skipped silently on that show rather than erroring on every event. Also asked before an erasure's removeMember(), including while the add-on is switched off everywhere, so it must not depend on anything the add-on sets up when it starts.
addMember( int $user_id, int $show_id, string $tier_slug ): bool Public — Grants the subscriber access to this show's community at the given tier. Return false on failure. Should be safe to call for somebody who is already a member.
removeMember( int $user_id, int $show_id ): bool Public — Revokes the subscriber's access to this show's community. Return false on failure. Should be safe to call for somebody who is already absent. Can be called for a show where the add-on is switched off, and when Benecaster deletes the subscriber's data. An erasure calls it even while the add-on is switched off for every show or its license has lapsed, on a request where nothing else of the add-on has started, so read your settings and credentials directly here.
updateMemberTier( int $user_id, int $show_id, string $old_tier, string $new_tier ): bool Public — Moves an existing member between this show's tiers. Both the old and new slugs are supplied so you can remove one role and add another where the platform has no single move operation. A move to a lower tier can be called for a show where the add-on is switched off.
onEpisodePublished( int $episode_id, int $show_id ): void Public — Called once per episode, after it is published and saved — announce it, or do nothing. Returns void because an announcement failing is not a reason to fail the publish. Called only for a show where isConfigured( $show_id ) is true.

Notes

Member methods are called from a background job, never during the checkout or webhook that changed the member's access. Return false or throw on failure: the call is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then shown as failed on the show's Community tab. A thrown exception's message is shown there to the podcaster, so it must never carry a credential.