Skip to main content

benecaster_download_logged

Action Premium

Fires after a download event is successfully written to the download log.

Use this hook to react to confirmed download activity — for example, to dispatch a background job that recalculates show stats, write a secondary audit record, or send a notification. This hook fires only when a log row was actually persisted; it does not fire when the benecaster_download_log_entry filter returned an empty array. Use benecaster_download_redirected if you need a hook that fires on every proxied download that is served, regardless of whether logging occurred.

Neither hook sees a download refused because the show’s licence is inactive. That refusal happens before the download is logged, so no log row is written and neither action fires — see benecaster_download_redirected for why a lapsed show’s download counts fall to follower traffic rather than to zero.

The $log_entry array contains the full row as persisted:

Key Type Description
episode_id int Episode post ID
show_id int Show post ID the episode belongs to
token_id int Token record ID used to authorize the request
user_id int WordPress user ID (0 if unauthenticated)
tier_slug string Subscriber tier at the time of download
ip_hash string SHA-256 hash of the requester’s IP address
byte_range string|null Value of the Range header, or null
client_app string Detected podcast app label
country_code string|null ISO 3166-1 alpha-2 country code, or null
region_code string|null ISO 3166-2 region code, or null
downloaded_at string UTC datetime (Y-m-d H:i:s) when the row was written

Parameters

Name Type Default Description
$episode_id int — Episode post ID that was downloaded
$user_id int — WordPress user ID of the subscriber; 0 for unauthenticated requests
$log_entry array — The full log row as persisted to the database

Examples

Recalculate show stats in the background

add_action(
    'benecaster_download_logged',
    function ( int $episode_id, int $user_id, array $log_entry ): void {
        wp_schedule_single_event(
            time(),
            'my_plugin_recalculate_show_stats',
            [ $log_entry['show_id'] ]
        );
    },
    10,
    3
);

Write a secondary audit record for a specific tier

add_action(
    'benecaster_download_logged',
    function ( int $episode_id, int $user_id, array $log_entry ): void {
        global $wpdb;
        if ( 'pro' !== $log_entry['tier_slug'] ) {
            return;
        }
        $wpdb->insert(
            $wpdb->prefix . 'my_compliance_log',
            [
                'episode_id'    => $episode_id,
                'user_id'       => $user_id,
                'country_code'  => $log_entry['country_code'],
                'downloaded_at' => $log_entry['downloaded_at'],
            ],
            [ '%d', '%d', '%s', '%s' ]
        );
    },
    10,
    3
);

Notes

Fires synchronously before the redirect response is sent. Keep callbacks fast. For non-trivial processing (external API calls, queue dispatch), use wp_schedule_single_event() or similar rather than blocking here.

$user_id of 0 indicates a request that passed token validation but has no associated WordPress account (e.g. a public feed download). Check $log_entry['token_id'] for the token that authorized it.

The $log_entry array reflects the row as actually persisted, including any modifications made by the benecaster_download_log_entry filter upstream.

Related Recipes

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

Powered by