PromotionService

Benecaster\Promotion\PromotionService

Drives the Promote to Bridge wizard’s run step and grace period management. The service creates subscriber accounts in the target bridge, writes grace period dates, and coordinates post-run reporting.

Methods

build_preview()

public function build_preview(
    int    $show_id,
    string $target_bridge_slug,
    array  $tier_map
): array

Returns a preview of the promotion run without executing it — subscriber counts per mapped tier.

Parameters:

Name	Type	Description
$show_id	int	Show post ID
$target_bridge_slug	string	Bridge slug from the wizard’s destination selection
$tier_map	array	Map of native_tier_slug => external_tier_id

Return: [ 'tiers' => [ ['slug' => '...', 'count' => N], ... ], 'total' => N ]

---

run()

public function run(
    int    $show_id,
    string $target_bridge_slug,
    array  $tier_map,
    int    $grace_days
): array

Executes the promotion. For each active subscriber in the show:

1. Calls BridgeWritable::create_member() on the target bridge
2. On success — writes promote_grace_period_ends_at and promoted_to_bridge to the subscriber’s record; existing feed token is preserved through the grace period
3. On skip (subscriber already exists in target) — records a skip
4. On error — records an error; does not halt the run

Fires benecaster_bridge_promote_complete when all rows are processed, even if all errored.

Return: [ 'promoted' => N, 'skipped' => N, 'errors' => N, 'grace_period_ends_at' => 'Y-m-d H:i:s' ]

Important: Native subscription records and feed tokens are intentionally left intact. The existing Benecaster subscription is not cancelled — the admin must cancel Stripe subscriptions separately.

---

clear_grace_period()

public function clear_grace_period( int $subscription_id ): bool

Clears the promote_grace_period_ends_at marker on a single subscriber record and re-enables token access. Used by the Promotion History panel’s “Clear grace” action.

Returns true on success, false when the record is not found.

---

extend_grace_period()

public function extend_grace_period( int $subscription_id, int $days ): bool

Adds $days to the subscriber’s current promote_grace_period_ends_at. If the grace period has already expired, extends from the current datetime instead.

Returns true on success, false when the record is not found.