Skip to main content

benecaster_export_sheets

Filter Free

Filters the available sheets for the “Your Data” XLSX export. Fires twice per export request: once during the UI render pass when building the sheet checkboxes in Settings > Your Data, and once during the generation pass when writing the XLSX file. During the UI render pass, $context date fields are empty strings.

Add-ons use this filter to register additional export sheets by pushing a sheet definition object onto $sheets and returning the modified array. Row data is provided separately via the benecaster_export_sheet_rows_sheet_id filter. A sheet registered here without a corresponding rows filter produces a sheet containing headers only.

Parameters

Name Type Default Description
$sheets array — Ordered array of sheet objects {id: string, title: string, description: string, columns: array, add_on: string|null}
$context array — Export context: {show_id: int|null, date_start: string, date_end: string}

Returns: array

Examples

Register custom donations export sheet

add_filter( 'benecaster_export_sheets', function( $sheets, $context ) {
    // Register a custom "Donations" export sheet from an add-on.
    $sheets[] = [
        'id'          => 'donations',
        'title'       => 'Donations',
        'description' => 'Listener Support donation transactions for the selected period.',
        'columns'     => [
            'date'      => 'Date',
            'email'     => 'Donor Email',
            'amount'    => 'Amount',
            'currency'  => 'Currency',
        ],
        'add_on'      => 'my-donations-addon',
    ];
    return $sheets;
}, 10, 2 );

Register sheet with add-on gate check

add_filter( 'benecaster_export_sheets', function ( array $sheets, array $context ): array {
    // ⚠ $context['show_id'] is int|null — null during the UI render
    // pass, when no show has been chosen yet. That is the one case
    // where the install-wide question is the right one to ask.
    $active = null === $context['show_id']
        ? benecaster_addon_is_active_for_any_show( 'sponsor-manager' )
        : benecaster_addon_is_active( 'sponsor-manager', (int) $context['show_id'] );
    if ( ! $active ) {
        return $sheets;
    }
    $sheets[] = [
        'id'          => 'sponsor_placements',
        'title'       => 'Sponsor Placements',
        'description' => 'All sponsor placements and click data for the selected date range.',
        'columns'     => [
            'episode_id'   => 'Episode ID',
            'sponsor_name' => 'Sponsor',
            'placement'    => 'Placement',
            'clicks'       => 'Clicks',
        ],
        'add_on'      => 'sponsor-manager',
    ];
    return $sheets;
}, 10, 2 );

Notes

Built-in sheet IDs are subscribers, subscription_events, shows, and episodes. During the UI render pass $context date fields are empty strings — avoid date-dependent logic in the sheet definition itself. A registered sheet without a corresponding benecaster_export_sheet_rows_sheet_id filter produces a sheet with headers only and no data rows.

Related Recipes

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

Powered by