SubscriptionRepository — Grace-Period Methods

Benecaster\Repository\SubscriptionRepository

Five public methods added in DB_VERSION 1.28.0 to support the Promote to Bridge grace period workflow.

These methods operate on the benecaster_subscriptions table. They require benecaster_db_version ≥ 1.28.0 — calls on older schema versions return false or empty arrays without erroring.

---

Methods

set_promote_grace_period()

public function set_promote_grace_period(
    int    $subscription_id,
    string $bridge_slug,
    string $ends_at
): bool

Writes promoted_to_bridge and promote_grace_period_ends_at on a subscription row. Called by PromotionService::run() for each promoted subscriber.

$ends_at — datetime string in MySQL Y-m-d H:i:s format.

---

clear_promote_grace_period()

public function clear_promote_grace_period( int $subscription_id ): bool

Sets promote_grace_period_ends_at = NULL and resets status to active for a given subscription row. Used by the Promotion History “Clear grace” admin action. Does not modify promoted_to_bridge — the bridge slug is preserved for history display.

---

mark_promote_grace_expired()

public function mark_promote_grace_expired( int $subscription_id ): bool

Sets subscription status to expired_grace. Called by GracePeriodExpiryCheck after token revocation.

---

find_grace_period_window()

public function find_grace_period_window(
    string $from,
    string $to
): array

Returns subscription rows where promote_grace_period_ends_at falls between $from and $to (inclusive) and status is active. Used by GracePeriodExpiryCheck’s reminder pass to find subscribers in the 6–8 day window.

$from / $to — datetime strings in MySQL Y-m-d H:i:s format.

---

find_all_by_show()

public function find_all_by_show( int $show_id, array $args = [] ): array

Returns all subscription rows for a show. $args supports:

Key	Type	Description
status	string|array	Filter to one or more status values
promoted_only	bool	When true, returns only rows with a non-null promoted_to_bridge
limit	int	Row limit
offset	int	Row offset for pagination

Used by GracePeriodExpiryCheck’s expiry pass and by PromotionService::build_preview().

---

Related

• GracePeriodExpiryCheck — the daily cron that calls find_grace_period_window() and mark_promote_grace_expired()
• SubscriptionRepository billing methods — the Phase 2 billing methods on the same class