Skip to main content

BridgeInterface

\Benecaster\Bridge\BridgeInterface

Interface Premium

The contract all membership bridges must implement. Add-on bridges implement this interface to integrate their target plugin’s subscription data with Benecaster’s token and feed system.

create_manual_membership() is part of the contract. Bridges that cannot programmatically create a member should use ManualMembershipUnsupportedTrait to inherit a throwing default, and must NOT return true from the benecaster_bridge_supports_manual_membership filter unless they implement the method directly.

Methods

Method Visibility Since Description
get_user_tier( int $user_id, int $show_id ): ?string Public — Abstract. Must return the internal tier slug for the user's active subscription on this show, or null if the user has no active subscription or the tier cannot be determined.
get_all_user_tiers( int $user_id, int $show_id ): array Public — Abstract. Must return every active internal tier slug for the user on the given show, as string[]. Used by FeedController to resolve which tier feeds the subscriber can access — a subscriber holding two memberships mapped to the same show should get the union of both tiers' episode sets. Returns [] when the user has no active mapped membership.
is_user_active( int $user_id, int $show_id ): bool Public — Abstract. Must return true when the user has any active subscription on the show — every built-in implementation defines this as get_user_tier() !== null.
get_all_tiers( int $show_id ): array Public — Abstract. Must return every tier available for mapping, each an associative array with at minimum 'id' (string|int) and 'name' (string).
on_subscription_activated( callable $callback ): void Public — Abstract. Must register $callback to fire when a membership becomes active — a brand-new subscription, a resubscription, or a payment-failure recovery.
on_subscription_cancelled( callable $callback ): void Public — Registers $callback for the end of a membership. Call it as $callback( int $user_id, int $show_id, string $reason = 'cancelled' ). $reason is a SubscriptionEndReason constant — EXPIRED when the target plugin reports a lapse (fixed term ran out, renewals gave up), otherwise CANCELLED; the third argument is optional and backward compatible, so two arguments still mean CANCELLED. A bridge should report expiry as well as cancellation — one that never hears its plugin's expiry leaves a lapsed member's token active (still counted as paying, never sent the cancellation email). Reporting an expiry for someone still subscribed is harmless; SubscriptionListener ignores it when a tier remains.
on_subscription_changed( callable $callback ): void Public — Abstract. Must register $callback to fire on a plan/tier change. Its callback ends in benecaster_subscription_tier_changed, which sends the Tier Change email, so every built-in membership-plugin bridge implements this as a no-op: MemberPress, WooCommerce Subscriptions, Paid Memberships Pro and Restrict Content Pro report a plan change as an activation on the subscriber's still-active token instead, which moves the tier and fires benecaster_subscription_tier_moved with no email.
on_subscription_renewed( callable $callback ): void Public — Abstract. Must register $callback to fire after a successful recurring payment that extends an existing membership.
on_payment_failed( callable $callback ): void Public — Abstract. Must register $callback to fire when a recurring payment fails. Coverage varies by target plugin — see each bridge's own page for what it can and cannot detect.
on_tier_saved( callable $callback ): void Public — Registers a callback that fires when a tier (level or product) is created or updated in the target plugin. Callback signature: fn( array $tier ): void, where $tier has 'id' (int, the plugin's external tier ID), 'name' (string), and 'price' (float|null — null means the price isn't resolvable for that plugin). The default implementation is a no-op; a bridge with no equivalent save event simply never calls it.
get_plugin_slug(): string Public — Abstract. Must return the bridge's slug — the value stored on a show and matched against the tier map's external-system column. 'null' for the inert bridge a show gets when none is configured; the target plugin's own slug for every other bridge.
create_manual_membership( int $user_id, int $show_id, string $tier_slug, ?string $expiry_at ): array Public — Abstract. Must provision the member record in the bridge's target plugin, mint a Benecaster token via TokenManager::generate(), stamp is_manual_grant = 1 via TokenRepository::set_manual_grant(), and return { subscription_id: int, token_prefix: string }. Bridges that do not support this operation should use ManualMembershipUnsupportedTrait.