Skip to main content

benecaster_addon_setup_checks

Filter Free

Registers setup reminders for an add-on that needs configuring before it works — an API key, a platform connection, a list to sync to. Each entry in $checks is a callable that returns null once its requirement is met, or a notice array while it is still missing.

Failing checks appear as the first rows of the Dashboard’s Needs attention section, not as WordPress admin notices. Each shows its message, a button when the notice has an action, and a × that hides it for that user. They are site-wide, so the same reminders show on every show’s dashboard. The checks run each time a dashboard loads, and a reminder disappears on its own as soon as its callable returns null; one the user hid comes back if the problem returns after being fixed.

Benecaster registers three checks of its own on this filter: a membership plugin connected, a tier mapped, and built-in membership with its Stripe keys and a tier. Your add-on’s checks appear alongside them.

Parameters

Name Type Default Description
$checks array — Array of callables. Each returns `null` when its condition is met, or a notice array when it is not. Notice keys: `key` (string, required — unique across every add-on; it identifies the reminder for hiding and for `requires`), `severity` (string, required — `'warning'` or `'error'`; an error shows a red ✕), `message` (string, required), `action_url` and `action_label` (strings, optional — give both or neither), and `requires` (string, optional — the `key` of another check; this reminder stays hidden while that one is failing).

Returns: array

Examples

One required setting

add_filter( 'benecaster_addon_setup_checks', function ( array $checks ): array {
    $checks[] = function (): ?array {
        // Requirement met: return null and the reminder disappears.
        if ( '' !== (string) get_option( 'my_addon_api_key', '' ) ) {
            return null;
        }

        return [
            'key'          => 'my_addon_api_key_missing',
            'severity'     => 'warning',
            'message'      => __( 'My Add-on needs an API key before it can sync.', 'my-addon' ),
            'action_url'   => admin_url( 'admin.php?page=my-addon-settings' ),
            'action_label' => __( 'Add API key', 'my-addon' ),
        ];
    };

    return $checks;
} );

A second step that waits for the first

add_filter( 'benecaster_addon_setup_checks', function ( array $checks ): array {
    $checks[] = function (): ?array {
        if ( get_option( 'my_addon_list_id' ) ) {
            return null;
        }

        return [
            'key'      => 'my_addon_list_missing',
            'severity' => 'warning',
            'message'  => __( 'Choose which list My Add-on syncs to.', 'my-addon' ),
            // Hidden until the API key check above passes.
            'requires' => 'my_addon_api_key_missing',
        ];
    };

    return $checks;
} );

Notes

Keep each callable cheap. It runs every time a dashboard loads: read options, transients or values you already have, and never make an HTTP request or a heavy query inside it.

Prefix key with your add-on's slug. If two callables return the same key, the first one wins and the other is skipped.

requires shows one step at a time. A chain can be any length, and hiding an earlier step does not reveal the next one while the earlier step is still unmet. A requires naming a key that is not failing — because it passed, is misspelt, or its add-on is not loaded — hides nothing.

Anything else is skipped silently: a callable returning a notice with no key or message, or a severity other than warning or error.

Affects

  • Dashboard → Needs attention

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