Filters reference
WordPress filters for customising REST API behaviour in Burst Statistics. Filters specific to share links are documented in Share links.
burst_get_data_request_args
Filters the normalized request arguments used by GET burst/v1/data/{type} before the data handler runs. Use this to inject or override parameters that are not part of the default allowed argument list.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$args | array | Normalized request arguments |
$type | string | Requested data type |
$request | WP_REST_Request | Original REST request object |
Show code
add_filter( 'burst_get_data_request_args', function( array $args, string $type, WP_REST_Request $request ): array {
// Inject custom comparison dates for the compare type.
if ( $type === 'compare' ) {
$args['compare_date_start'] = sanitize_text_field( $request->get_param( 'compare_date_start' ) );
$args['compare_date_end'] = sanitize_text_field( $request->get_param( 'compare_date_end' ) );
}
return $args;
}, 10, 3 );
burst_get_data
Fallback filter for custom GET burst/v1/data/{type} handlers. Fires when the requested {type} does not match any built-in type. Use this to add support for custom data types without modifying core files.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array | Current data array (empty [] by default for unknown types) |
$type | string | Requested data type |
$args | array | Normalized request arguments |
$request | WP_REST_Request | Original REST request object |
Show code
add_filter( 'burst_get_data', function( array $data, string $type, array $args, WP_REST_Request $request ): array {
if ( $type === 'my_custom_type' ) {
$data = [
'value' => get_my_custom_metric( $args['date_start'], $args['date_end'] ),
];
}
return $data;
}, 10, 4 );
burst_sanitize_arg
Filters sanitization for custom request arguments in the data endpoint. Return null to fall back to Burst's default handling, or return a sanitized value to override it.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed / null | Return a sanitized value to override, or null to use default handling |
$key | string | Argument name |
$raw | mixed | Raw value from the request |
Show code
add_filter( 'burst_sanitize_arg', function( $value, string $key, $raw ) {
if ( $key === 'my_custom_param' ) {
return absint( $raw );
}
return $value; // null — let Burst handle it.
}, 10, 3 );
burst_statistics_allowed_filter_keys
Filters the list of accepted keys in the filters request parameter. Use this to allowlist additional filter keys for custom data integrations.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$keys | array | Current list of allowed filter key strings |
$is_strict | bool | Whether the request is in strict mode (i.e. the user is not an admin) |
Show code
add_filter( 'burst_statistics_allowed_filter_keys', function( array $keys, bool $is_strict ): array {
if ( ! $is_strict ) {
$keys[] = 'my_custom_dimension';
}
return $keys;
}, 10, 2 );
burst_rest_api_fields_get
Filters the response payload returned by GET burst/v1/fields/get. Use this to expose additional metadata alongside the core fields and menu configuration.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$response | array | The full fields/menu response array |
Show code
add_filter( 'burst_rest_api_fields_get', function( array $response ): array {
$response['my_plugin_data'] = get_my_plugin_metadata();
return $response;
} );
burst_rest_api_goals_get
Filters the goals payload returned by the goals GET endpoints. Applied to both the standard goals list and the share-link-safe goals response.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$response | array | The goals response array |
Show code
add_filter( 'burst_rest_api_goals_get', function( array $response ): array {
// Add a custom field to each goal.
if ( ! empty( $response['goals'] ) ) {
foreach ( $response['goals'] as &$goal ) {
$goal['my_field'] = get_my_goal_data( $goal['id'] );
}
}
return $response;
} );
burst_countries
Filters the country lookup array returned for country option lists in the admin app.
Expected format: associative array keyed by ISO 3166-1 alpha-2 country code.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$countries | array | Associative array of [ 'US' => 'United States', ... ] |
burst_continents
Filters the continent lookup array returned for continent option lists in the admin app.
Expected format: associative array keyed by two-letter continent code.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$continents | array | Associative array of [ 'EU' => 'Europe', ... ] |
burst_endpoint_tab_map
Filters the map of REST endpoint paths to dashboard tab slugs. Burst uses this map to resolve which tab a share-link viewer is requesting, so the request can be matched against the tabs allowed by the active share token. Use this to register custom endpoints so they fall under the correct shareable tab, or to mark an endpoint as unrestricted with the all slug.
The endpoint path is relative to the burst/v1 namespace (for example data/insights, not /wp-json/burst/v1/data/insights). Endpoints that are not present in the map are denied for shared viewers by default.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$map | array | Associative array of [ 'data/insights' => 'statistics', ... ] |
Show code
add_filter( 'burst_endpoint_tab_map', function( array $map ): array {
// Expose a custom endpoint to share-link viewers on the statistics tab.
$map['data/my_custom_widget'] = 'statistics';
return $map;
} );
burst_datatable_id_tab_map
Filters the map of datatable IDs to dashboard tab slugs. The generic datatable endpoints (data/datatable/{id} and data/ecommerce/datatable/{id}) resolve the active tab from the requested datatable ID rather than the endpoint path. Use this to register custom datatable IDs so they map onto the correct shareable tab.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$map | array | Associative array of [ 'statistics_pages' => 'statistics', ... ] |
Show code
add_filter( 'burst_datatable_id_tab_map', function( array $map ): array {
$map['my_custom_datatable'] = 'statistics';
return $map;
} );
burst_datatable_metric_allow_list
Filters the per-datatable allowlist of metric keys accepted by the datatable endpoints. Incoming metrics arguments are intersected with the allowlist for the requested datatable ID, so any metric not declared here is silently dropped. Use this to register custom metrics for a datatable, or to register an entirely new datatable ID.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$allow_list | array | Associative array of [ 'statistics_pages' => [ 'page_url', 'pageviews', ... ], ... ] |
Show code
add_filter( 'burst_datatable_metric_allow_list', function( array $allow_list ): array {
// Add a custom metric to the pages datatable.
$allow_list['statistics_pages'][] = 'my_custom_metric';
// Register a new datatable with its own metric set.
$allow_list['my_custom_datatable'] = [ 'page_url', 'pageviews', 'visitors' ];
return $allow_list;
} );
burst_datatable_pre_data
Short-circuits the default datatable database query. Return a non-null array to use that data as the datatable response and bypass the built-in query for the requested datatable ID. Return null to let Burst run the default query. Use this to serve synthetic, cached, or remote data for custom datatable IDs.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array / null | Pre-computed datatable rows, or null to fall through to the default query |
$args | array | Datatable arguments including id, date_start, date_end, metrics, filters, group_by, limit |
Show code
add_filter( 'burst_datatable_pre_data', function( ?array $data, array $args ): ?array {
if ( ( $args['id'] ?? null ) === 'my_custom_datatable' ) {
return [
[ 'page_url' => '/example', 'pageviews' => 1200, 'visitors' => 950 ],
[ 'page_url' => '/about', 'pageviews' => 480, 'visitors' => 410 ],
];
}
return $data; // null — let Burst run the default query.
}, 10, 2 );