Skip to main content

benecaster_over_limit_flags_evaluated

Action Free

Fires after each daily license validation cycle when the over-limit flag manager has finished syncing the is_over_limit column for all subscriber tokens. $count reflects the total number of currently flagged tokens after the evaluation — not the change from the previous cycle. $ids contains all currently flagged token IDs, not just newly flagged ones, ordered by token creation date descending.

This hook fires on every validation cycle, including cycles where no flags changed and cycles where $count is zero (meaning all over-limit flags were cleared). Does not fire on unlimited plans (Pro, Multi-Show, Studio).

The daily run validates each connected show in turn, so the hook fires once per connected show, and $show_uuid names the show whose validation ran the evaluation. $count and $ids cover the license’s tokens, so every call in one run carries the same figures. A listener that takes only the first two arguments keeps working.

Parameters

Name Type Default Description
$count int — Number of tokens currently flagged `is_over_limit = 1` after this evaluation cycle
$ids int[] — Token IDs that are currently flagged — empty array when `$count` is 0
$show_uuid string — The `_benecaster_show_uuid` of the show whose validation ran this evaluation

Examples

Alert on new overage, log on clearance

add_action( 'benecaster_over_limit_flags_evaluated', function ( int $count, array $ids ): void {
    $prev_count = (int) get_option( 'my_plugin_over_limit_count', 0 );

    if ( $count > 0 && $prev_count === 0 ) {
        // Newly over-limit — send an alert.
        wp_mail(
            get_option( 'admin_email' ),
            'Benecaster: subscribers over your plan limit',
            sprintf(
                '%d subscriber(s) are now receiving your public feed instead of their private tier. '
                . "Upgrade your plan at benecaster.com to restore their access.\n\nToken IDs: %s",
                $count,
                implode( ', ', $ids )
            )
        );
    }

    if ( $count === 0 && $prev_count > 0 ) {
        error_log( 'Benecaster: over-limit flags cleared. Private feed access restored for all subscribers.' );
    }

    update_option( 'my_plugin_over_limit_count', $count );
}, 10, 2 );

Notes

Does not fire on unlimited plans. $count is the absolute current count, not a delta — store the previous count in a WordPress option to detect changes between cycles. Because the hook fires once per connected show, the second and later calls in a run see the count the first call stored and change nothing. $ids contains token record IDs (from the tokens table), not WordPress user IDs.

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