Tasks

The tasks system in Burst Statistics surfaces actionable notices in the admin dashboard. Tasks notify site administrators about warnings, errors, plugin milestones, promotional offers, and configuration recommendations. Developers can register custom tasks using the burst_tasks filter.

Overview

Tasks are defined as PHP arrays in includes/Admin/App/config/tasks.php and merged at runtime via the burst_tasks filter. Each task has an ID, a message, an icon type, and an optional condition that controls when it appears.

Active task IDs are stored in the WordPress option burst_tasks. The admin UI reads this list and merges it with the full task definitions to determine what to display.

Task lifecycle

Registration — Tasks are defined in the config file or added by the burst_tasks filter.
Activation — Tasks with condition.type = activation are written to burst_tasks on plugin activation.
Validation — A scheduled event (burst_validate_tasks) runs every time task validation is triggered. It evaluates all serverside conditions and adds or removes task IDs from burst_tasks accordingly.
Display — get_tasks() reads burst_tasks, merges active IDs with task definitions, filters out dismissed tasks, and sorts results (warnings first, then open, then other).
Dismissal — When a user dismisses a task, it is removed from burst_tasks. If the task has dismiss_permanently = true, its ID is also stored in burst_tasks_permanently_dismissed and will never be re-added.

Task definition fields

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the task. Sanitized with `sanitize_title()` when stored.
`msg`	string	No	Translated message shown to the user. Supports HTML.
`icon`	string	No	Icon type that controls the label and sort order. See Icon types. Defaults to `'open'`.
`url`	string	No	Link URL. Relative paths are prefixed with the Burst website URL and UTM parameters. Paths starting with `#` are treated as internal links. Full `https://` URLs are passed through unchanged.
`condition`	array	No	Controls when the task is active. See Condition types.
`dismissible`	bool	No	Whether the user can dismiss the task.
`dismiss_permanently`	bool	No	If `true`, dismissing the task stores it in `burst_tasks_permanently_dismissed` and it will never be shown again, even if the condition becomes true again.
`plusone`	bool	No	If `true`, the task increments the admin-bar badge counter.
`fix`	string	No	Identifier for a fix action available in the UI. Can be a WordPress option name (to toggle an option) or a Burst action name.

Icon types

The icon field determines the badge label shown alongside the task and affects sort order.

Icon value	Label	Sort priority
`warning`	Warning	1st (top)
`error`	Error	1st (top)
`open`	Open	2nd
`completed`	Completed	3rd
`new`	New!	3rd
`sale`	Sale	3rd
`offer`	Offer	3rd
`milestone`	Milestone	3rd
`insight`	Update	3rd
`pro`	Pro	3rd

Tasks with icon = 'success' are given a status of 'completed'; all others receive 'open'.

caution

If the site administrator has enabled the Dismiss non-error notices setting (dismiss_non_error_notices), only tasks with icon = 'error' will be displayed, regardless of their condition.

Condition types

The condition field is an array with a required type key.

`activation`

The task is added to burst_tasks once when the plugin activates. It has no server-side re-evaluation; it persists until dismissed.

'condition' => [
    'type' => 'activation',
],

`serverside`

The task is evaluated on every task validation run. The condition resolves to a boolean via a function or constant key.

'condition' => [
    'type'     => 'serverside',
    'function' => 'MyPlugin\MyClass::is_active()',
],

If the condition is true, the task is added. If false, the task is dismissed (unless it has dismiss_permanently).

Supported function formats:

Format	Example	Description
WordPress option check	`'wp_option_burst_missing_tables'`	Returns `true` if the option exists (is not `false`). Strip the `wp_option_` prefix to get the option name.
Static method call	`'Burst\Admin\Admin::is_bf()'`	Calls `ClassName::methodName()`.
Instantiated method call	`'(new Burst\Admin\Milestones())->pageviews_milestone_reached()'`	Instantiates the class, then calls the method.
Chained call	`'base()->class->method'`	Calls a method on a chained object.
Inversion	Prefix any format with `!`	Negates the result.

Using a constant:

'condition' => [
    'type'     => 'serverside',
    'constant' => 'MY_PLUGIN_CONSTANT',
],

Returns true if the constant is defined. Prefix with ! to invert.

`clientside`

The task is always included in the task list sent to the browser. The front-end JavaScript evaluates whether to display it. Client-side tasks bypass the burst_tasks option entirely — they are never filtered by has_task().

'condition' => [
    'type' => 'clientside',
],

Built-in tasks

The following tasks ship with Burst Statistics v3.3.0.

ID	Icon	Condition type	Dismissible	Permanent dismiss	plusone
`bf_notice`	sale	serverside	Yes	Yes	Yes
`cm_notice`	sale	serverside	Yes	Yes	Yes
`leave-feedback`	completed	activation	Yes	No	—
`join-discord`	completed	activation	Yes	No	—
`ecommerce_integration`	new	—	Yes	No	No
`cron`	warning	—	No	No	—
`malicious_data_removal`	warning	serverside (`wp_option_burst_cleanup_uid_visits`)	Yes	No	—
`trial_offer_loyal_users`	sale	—	Yes	No	Yes
`php_error_detected`	warning	serverside (`wp_option_burst_php_error_detected`)	Yes	No	—
`missing_tables`	warning	serverside (`wp_option_burst_missing_tables`)	Yes	No	—
`pageviews_milestone`	milestone	serverside (`Burst\Admin\Milestones::pageviews_milestone_reached()`)	Yes	No	No
`live_visitors`	insight	clientside	No	No	No
`multi_domain_setup_detected`	warning	serverside (`wp_option_burst_is_multi_domain`)	Yes	Yes	No
`filters_in_url`	new	—	Yes	No	No
`opt-in-sharing`	new	—	Yes	No	No
`turbo_mode_recommended`	warning	—	Yes	No	No

Tasks with no condition key have no automatic lifecycle management — they must be added and removed programmatically or they remain active once inserted into burst_tasks.

WordPress options

Option	Type	Description
`burst_tasks`	array	Active task IDs. Each entry is a `sanitize_title()`-processed string.
`burst_tasks_permanently_dismissed`	array	Task IDs that have been permanently dismissed and will never be re-added.

Transient:

Transient	TTL	Description
`burst_plusone_count`	1 day	Cached count of active tasks that have `plusone = true`. Cleared on task validation and dismissal.

Hooks and filters

burst_tasks

Filters the full array of task definitions before they are used anywhere. Use this filter to add, remove, or modify tasks.

Parameters:

Parameter	Type	Description
`$tasks`	array	Indexed array of task definition arrays as described in Task definition fields.

Example — adding a custom task:

add_filter( 'burst_tasks', function( array $tasks ): array {
    $tasks[] = [
        'id'          => 'my_custom_task',
        'msg'         => __( 'Your custom notice message.', 'my-plugin' ),
        'icon'        => 'warning',
        'dismissible' => true,
        'condition'   => [
            'type'     => 'serverside',
            'function' => 'MyPlugin\Tasks::is_condition_met()',
        ],
    ];
    return $tasks;
} );

Example — adding a task with a WordPress option condition:

add_filter( 'burst_tasks', function( array $tasks ): array {
    $tasks[] = [
        'id'          => 'my_option_task',
        'msg'         => __( 'Something requires your attention.', 'my-plugin' ),
        'icon'        => 'warning',
        'dismissible' => true,
        'condition'   => [
            'type'     => 'serverside',
            // Active when get_option('my_plugin_error') !== false.
            'function' => 'wp_option_my_plugin_error',
        ],
    ];
    return $tasks;
} );

Example — removing a built-in task:

add_filter( 'burst_tasks', function( array $tasks ): array {
    return array_filter( $tasks, fn( $t ) => $t['id'] !== 'ecommerce_integration' );
} );

burst_dismiss_task

Fires when a task is dismissed by the user, before it is removed from burst_tasks.

Parameters:

Parameter	Type	Description
`$task_id`	string	The ID of the task being dismissed.

Example:

add_action( 'burst_dismiss_task', function( string $task_id ): void {
    if ( $task_id === 'my_custom_task' ) {
        // Run cleanup when user dismisses your task.
        delete_option( 'my_plugin_error' );
    }
} );

Developer API

The Tasks class (Burst\Admin\Tasks) is accessible via burst()->tasks.

`get_raw_tasks(): array`

Returns the complete task definitions array after applying the burst_tasks filter and resolving URLs. Does not filter by active status.

`get_tasks(): array`

Returns the filtered, sorted list of tasks for display. Removes tasks not in burst_tasks (except clientside tasks), applies the dismiss_non_error_notices setting, deduplicates by ID, and sorts warnings to the top.

`add_task( string $task_id ): void`

Inserts a task ID into burst_tasks. Has no effect if the task is permanently dismissed.

burst()->tasks->add_task( 'my_custom_task' );

`dismiss_task( string $task_id ): void`

Removes a task ID from burst_tasks and fires burst_dismiss_task. If the task has dismiss_permanently = true, also adds it to burst_tasks_permanently_dismissed. Clears the burst_plusone_count transient.

burst()->tasks->dismiss_task( 'my_custom_task' );

`has_task( string $task_id ): bool`

Returns true if the task ID is currently in burst_tasks.

if ( burst()->tasks->has_task( 'my_custom_task' ) ) {
    // Task is active.
}

`get_task_by_id( string $task_id ): ?array`

Returns the task definition array for a given ID, or null if not found.

$task = burst()->tasks->get_task_by_id( 'cron' );

`schedule_task_validation(): void`

Schedules a single burst_validate_tasks cron event 30 seconds from now, if one is not already scheduled. Always use this instead of calling validate_tasks() directly.

burst()->tasks->schedule_task_validation();

`add_initial_tasks(): void`

Inserts all activation-type tasks into burst_tasks. Called automatically on plugin activation.

`undismiss_task( string $task_id ): bool`

Removes a task ID from burst_tasks_permanently_dismissed, allowing it to be re-added by a future validation run. Returns true if the task was found and removed.

burst()->tasks->undismiss_task( 'my_custom_task' );

`plusone_count(): int`

Returns the number of currently active tasks with plusone = true and icon !== 'success'. Result is cached in the burst_plusone_count transient for one day. Returns 0 if the current user cannot manage Burst.

Complete custom task example

/**
 * Register a custom Burst task that warns when a specific option is set.
 */
add_filter( 'burst_tasks', function( array $tasks ): array {
    $tasks[] = [
        'id'          => 'my_plugin_api_warning',
        'msg'         => __( 'My Plugin: API key is missing. Please configure it in the settings.', 'my-plugin' ),
        'icon'        => 'warning',
        'url'         => admin_url( 'options-general.php?page=my-plugin' ),
        'dismissible' => true,
        'plusone'     => true,
        'condition'   => [
            'type'     => 'serverside',
            // Active when get_option('my_plugin_api_missing') is not false.
            'function' => 'wp_option_my_plugin_api_missing',
        ],
    ];
    return $tasks;
} );

// Set the option to trigger the task, then schedule validation.
add_action( 'init', function(): void {
    if ( get_option( 'my_plugin_api_key' ) === false ) {
        update_option( 'my_plugin_api_missing', true );
        if ( function_exists( 'burst' ) ) {
            burst()->tasks->schedule_task_validation();
        }
    }
} );

// Clean up when the task is dismissed.
add_action( 'burst_dismiss_task', function( string $task_id ): void {
    if ( $task_id === 'my_plugin_api_warning' ) {
        delete_option( 'my_plugin_api_missing' );
    }
} );

Overview​

Task lifecycle​

Task definition fields​

Icon types​

Condition types​

activation​

serverside​

clientside​

Built-in tasks​

WordPress options​

Hooks and filters​

burst_tasks​

burst_dismiss_task​

Developer API​

get_raw_tasks(): array​

get_tasks(): array​

add_task( string $task_id ): void​

dismiss_task( string $task_id ): void​

has_task( string $task_id ): bool​

get_task_by_id( string $task_id ): ?array​

schedule_task_validation(): void​

add_initial_tasks(): void​

undismiss_task( string $task_id ): bool​

plusone_count(): int​

Complete custom task example​