`benecaster_addon_setup_checks`

Filter Free Since v1.0.0

Registers persistent admin setup notices for add-ons that require external configuration before functioning — such as an API key, platform connection, or OAuth link. Each entry in the $checks array is a callable that returns null when the requirement is satisfied, or a notice array when it is still failing.

SetupNoticeManager runs this filter on admin_init, evaluates every callable, and surfaces failing notices to the current user. Notices disappear automatically the moment their callable returns null — no manual dismissal is required once the issue resolves. Dismissed notices persist per-user in user meta and re-surface if the same condition fails again after a later resolution. Benecaster registers two baseline checks by default — check_bridge_configured and check_tier_mapped — and your add-on’s checks appear alongside these.

Parameters

Name	Type	Default	Description
`$checks`	`array`	—	Array of callables. Each callable returns `null` when its condition is met, or a notice array when the condition is still failing. Notice array keys: `key` (string, required — unique identifier used for deduplication and dismiss-state tracking), `severity` (string, required — `'warning'` or `'error'`), `message` (string, required — human-readable explanation of what needs to be configured), `action_url` (string, optional — URL for the action button), `action_label` (string, optional — label for the action button).

Returns: array

Examples

Structured check array (YAML variant)

add_filter( 'benecaster_addon_setup_checks', function( $checks ) {
    // Register a setup check that surfaces a notice until the API key is saved.
    $checks[] = [
        'addon_slug'   => 'my-service-addon',
        'requirements' => [
            [
                'key'          => 'api_key_saved',
                'check'        => fn() => (bool) get_option( '_my_service_api_key' ),
                'message'      => 'My Service add-on requires an API key to function.',
                'action_label' => 'Add API key',
                'action_url'   => admin_url( 'admin.php?page=benecaster-settings&section=my-service' ),
            ],
        ],
    ];
    return $checks;
} );

Callable check returning notice array

add_filter( 'benecaster_addon_setup_checks', function ( array $checks ): array {
    $checks[] = function (): ?array {
        // Issue resolved — return null so the notice disappears.
        if ( get_option( 'my_addon_api_key' ) !== '' ) {
            return null;
        }

        // Issue persists — return a notice payload.
        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;
} );

Notes

Keep callables fast — they run on every admin page load. Cache expensive lookups with get_transient() or get_option(). Database queries and remote API calls in setup checks will slow every admin screen.

This is a Free filter. It fires regardless of license status.

Two additional SetupNoticeManager behaviors: (1) Duplicate keys are deduplicated — if multiple callables return the same key, the first one wins. (2) Invalid returns are silently skipped — a callable returning anything other than null or a valid array (e.g. missing key, invalid severity) is ignored. Dismiss state is stored in user meta under the key _benecaster_setup_notice_dismissed_{key}.

Affects

WordPress Admin Notices