id, [
'toplevel_page_valuespace',
'valuespace_page_valuespace-billing',
'valuespace_page_valuespace-events',
'options_page_vasp-info',
], true);
}
function vasp_enqueue_notice_assets() {
if (!vasp_is_plugin_admin_screen()) {
return;
}
wp_enqueue_style('valuespace-notices', VASP_PLUGIN_URL . 'admin/css/notices.css', [], VASP_VERSION);
wp_enqueue_script('valuespace-notices', VASP_PLUGIN_URL . 'admin/js/notices.js', ['jquery'], VASP_VERSION, true);
wp_localize_script('valuespace-notices', 'vaspNotices', [
'dismissNotice' => __('Dismiss this notice.', 'valuespace'),
'ajaxUrl' => admin_url('admin-ajax.php'),
'dismissNonce' => wp_create_nonce('vasp_dismiss_notice'),
]);
}
// ---------------------------------------------------------------------------
// Suppress helpers
// ---------------------------------------------------------------------------
/**
* Check whether a notice suppress key is active (user dismissed it within 24 h).
*
* @param string $key Suppress key (e.g. 'connection_lost').
* @return bool
*/
function vasp_is_notice_suppressed(string $key): bool {
return (bool) get_transient(VASP_TRANSIENT_NOTICE_SUPPRESSED_PREFIX . $key);
}
/**
* Suppress a notice for 24 hours.
* Called by the AJAX dismiss handler when the user clicks ✕.
*
* @param string $key Suppress key.
* @return void
*/
function vasp_suppress_notice(string $key): void {
vasp_set_dynamic_transient(VASP_TRANSIENT_NOTICE_SUPPRESSED_PREFIX . $key, true, DAY_IN_SECONDS);
}
// ---------------------------------------------------------------------------
// HTML builder — single function used by every notice path
// ---------------------------------------------------------------------------
/**
* Build a WP admin notice div.
*
* @param string $message User-facing message (already escaped by caller or escaped here).
* @param string $type 'error' | 'warning' | 'success' | 'info'.
* @param int $auto_dismiss Seconds before auto-removal (0 = never).
* @param array $actions Optional CTA buttons.
* Each entry: ['label' => string, 'url' => string,
* 'style' => 'primary|secondary|link', 'target' => '']
* @param string $suppress_key When set, adds data-suppress-key for the JS dismiss handler.
* @param string $description Optional longer explanation rendered below the title.
* @return string HTML.
*/
function vasp_show_notice(
string $message,
string $type = 'info',
int $auto_dismiss = 0,
array $actions = [],
string $suppress_key = '',
string $description = ''
): string {
$message_html = $description !== ''
? '' . esc_html($message) . '
'
. nl2br(esc_html($description), false) . ''
: nl2br(esc_html($message), false);
$dismiss_attr = $auto_dismiss > 0
? ' data-auto-dismiss="' . esc_attr((string) ($auto_dismiss * 1000)) . '"'
: '';
$suppress_attr = $suppress_key !== ''
? ' data-suppress-key="' . esc_attr($suppress_key) . '"'
: '';
$type_attr = ' data-notice-type="' . esc_attr($type) . '"';
$buttons_html = '';
foreach ($actions as $action) {
if (empty($action['url']) || empty($action['label'])) {
continue;
}
$style = in_array($action['style'] ?? '', ['primary', 'secondary', 'link'], true)
? $action['style']
: 'secondary';
$target = !empty($action['target']) ? ' target="' . esc_attr($action['target']) . '"' : '';
$class = $style === 'link'
? 'vasp-notice-details-link'
: 'button button-' . $style . ' button-small vasp-notice-action-button';
$buttons_html .= sprintf(
' %s',
esc_url($action['url']),
esc_attr($class),
$target,
esc_html($action['label'])
);
}
return sprintf(
'
',
esc_attr($type),
$dismiss_attr,
$suppress_attr,
$type_attr,
$message_html,
$buttons_html
);
}
/**
* Shorthand: error notice (no auto-dismiss).
*
* @param string $message
* @return string HTML
*/
function vasp_show_error(string $message): string {
return vasp_show_notice($message, 'error');
}
/**
* Shorthand: success notice with 6-second auto-dismiss.
*
* @param string $message
* @return string HTML
*/
function vasp_show_success(string $message): string {
return vasp_show_notice($message, 'success', 6);
}
/** Return whether a value is one of the plugin's registered message codes. */
function vasp_notice_is_message_code(string $value): bool {
$groups = get_defined_constants(true);
$user_constants = is_array($groups['user'] ?? null) ? $groups['user'] : [];
foreach ($user_constants as $name => $constant_value) {
if ((strpos((string) $name, 'VASP_ERROR_') === 0 || strpos((string) $name, 'VASP_MSG_') === 0)
&& is_string($constant_value)
&& hash_equals($constant_value, $value)) {
return true;
}
}
return false;
}
// ---------------------------------------------------------------------------
// Transient notice writer (OAuth callbacks, redirects, cron failures)
// ---------------------------------------------------------------------------
/**
* Queue an admin notice to be displayed on the next plugin page load.
*
* This is the canonical way to persist a notice across a redirect.
* For synchronous page-load errors, return WP_Error to the caller instead.
*
* @param string $message User-facing message OR a VASP_ERROR_* / VASP_MSG_* constant.
* @param string $type 'error' | 'warning' | 'success' | 'info'. Default 'error'.
* @param array $actions Optional CTA buttons: [['label','url','style','target'], ...].
* @param int $ttl Transient TTL in seconds. Default 5 minutes.
* @param int $auto_dismiss Seconds before auto-removal (0 = never; use 6 for success).
* @param string $description Optional longer explanation rendered below the title.
* @return void
*/
function vasp_queue_admin_notice(
string $message,
string $type = 'error',
array $actions = [],
int $ttl = 300, // 5 * MINUTE_IN_SECONDS — arithmetic not allowed in defaults
int $auto_dismiss = 0,
string $description = ''
): void {
// Already-localized messages must not be remapped to the generic
// unknown-error fallback merely because they are not machine codes.
if (function_exists('vasp_get_error_message')
&& vasp_notice_is_message_code($message)) {
$message = vasp_get_error_message($message);
}
$existing = get_transient(VASP_TRANSIENT_ADMIN_NOTICE);
if ($existing !== false && ($existing['notice_type'] ?? '') === $type) {
// Append if not already in the string
if (strpos($existing['user_message'], $message) === false) {
$message = $existing['user_message'] . "\n" . $message;
}
// Merge actions
$actions = array_merge($existing['actions'] ?? [], $actions);
// Take the max auto_dismiss
$auto_dismiss = max((int)($existing['auto_dismiss'] ?? 0), $auto_dismiss);
if ($description === '') {
$description = (string) ($existing['description'] ?? '');
}
}
$payload = [
'user_message' => $message,
'notice_type' => $type,
'auto_dismiss' => $auto_dismiss,
'actions' => $actions,
'description' => $description,
];
set_transient(VASP_TRANSIENT_ADMIN_NOTICE, $payload, $ttl);
if (function_exists('vasp_log')) {
vasp_log('Admin notice queued', 'info', ['notice_type' => $type]);
}
}
// ---------------------------------------------------------------------------
// Transient notice consumer (admin_notices hook, plugin pages only)
// ---------------------------------------------------------------------------
function vasp_render_queued_admin_notice() {
if (!current_user_can('manage_options') || !vasp_is_plugin_admin_screen()) {
return;
}
$notice = get_transient(VASP_TRANSIENT_ADMIN_NOTICE);
if ($notice === false) {
return;
}
delete_transient(VASP_TRANSIENT_ADMIN_NOTICE);
$message = $notice['user_message'] ?? '';
$notice_type = $notice['notice_type'] ?? 'error';
$auto_dismiss = (int) ($notice['auto_dismiss'] ?? 0);
$actions = $notice['actions'] ?? [];
$description = (string) ($notice['description'] ?? '');
if (empty($message)) {
return;
}
if (function_exists('vasp_log')) {
vasp_log('Admin notice rendered', 'info', ['notice_type' => $notice_type]);
}
// Suppress the "Go to Settings" CTA when we're already on the settings page.
if (!empty($actions) && isset($_GET['page']) && $_GET['page'] === 'valuespace') {
$actions = array_filter($actions, function ($a) {
$url = $a['url'] ?? '';
return strpos($url, 'page=valuespace') === false
|| strpos($url, 'page=vasp-') !== false; // keep billing/events links
});
$actions = array_values($actions);
}
echo wp_kses_post(vasp_show_notice($message, $notice_type, $auto_dismiss, $actions, '', $description));
}