'tecc', * 'option' => 'tecc_v2_welcome', // 'show' | 'done' * 'settings_url' => admin_url( 'admin.php?page=...' ), * 'screens' => array( 'plugins', '' ), * 'i18n' => array( ... ), // ALREADY TRANSLATED by the host * ) ); * * Three exits, deliberately different: * "See new settings" -> saves the dismissal AND goes to the panel * "Dismiss" -> saves the dismissal * the x -> soft close, saves NOTHING, so it returns next load * * As with CPFM_Review, this never calls __(): the host passes translated copy, * so the strings stay extractable in the host's own domain. * * @package CoolPlugins\CPFM * @since 1.0.0 */ if ( ! defined( 'ABSPATH' ) ) { exit; } if ( ! class_exists( 'CPFM_Welcome_Notice' ) ) { /** * Registry + renderer for the one-time upgrade announcement. */ final class CPFM_Welcome_Notice { /** * Registered plugin configs, keyed by id. * * @var array> */ private static $plugins = array(); /** * Whether a notice already rendered this request. * * @var bool */ private static $rendered = false; /** * Whether the shared assets were printed this request. * * @var bool */ private static $printed = false; /** * Register a plugin's welcome notice. * * @param array $config See the file docblock. * @return bool */ public static function cpfm_register( $config ) { $config = is_array( $config ) ? $config : array(); $id = isset( $config['id'] ) ? sanitize_key( $config['id'] ) : ''; if ( '' === $id || empty( $config['option'] ) ) { return false; } $config = array_merge( array( 'id' => $id, 'option' => '', 'capability' => 'manage_options', 'settings_url' => '', 'screens' => array(), // Opt out of core's notice relocation (custom full-bleed pages). 'inline_screens' => array(), // Screens where the HOST renders it itself via // maybe_render( false ); the admin_notices hook stays quiet. 'defer_screens' => array(), 'i18n' => array(), ), $config ); $config['id'] = $id; $config['option'] = sanitize_key( $config['option'] ); self::$plugins[ $id ] = $config; self::cpfm_boot(); return true; } /** * Wire the shared hooks exactly once, however many plugins register. * * @return void */ private static function cpfm_boot() { static $booted = false; if ( $booted ) { return; } $booted = true; if ( ! function_exists( 'add_action' ) ) { return; } add_action( 'admin_init', array( __CLASS__, 'cpfm_handle_dismiss' ) ); add_action( 'admin_notices', array( __CLASS__, 'cpfm_maybe_render' ) ); } /** * Config for an id, or null. * * @param string $id Plugin id. * @return array|null */ public static function cpfm_config( $id ) { $id = sanitize_key( $id ); return isset( self::$plugins[ $id ] ) ? self::$plugins[ $id ] : null; } /** * Persistently dismiss via the nonce-guarded link, then clean the URL. * * @return void */ public static function cpfm_handle_dismiss() { if ( ! isset( $_GET['cpfm-welcome'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- nonce checked below, after we know which plugin. return; } $id = sanitize_key( wp_unslash( $_GET['cpfm-welcome'] ) ); // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- ditto. $config = self::cpfm_config( $id ); if ( ! $config ) { return; } check_admin_referer( 'cpfm_welcome_' . $id ); if ( ! current_user_can( $config['capability'] ) ) { return; } update_option( $config['option'], 'done' ); wp_safe_redirect( remove_query_arg( array( 'cpfm-welcome', '_wpnonce' ) ) ); exit; } /** * Render the first eligible plugin's notice on an allowed screen. * * @param bool $from_hook True when called by `admin_notices`. WP_Hook * always supplies one argument (the empty string), * so only a literal false counts as a direct call. * @return void */ public static function cpfm_maybe_render( $from_hook = true ) { $from_hook = ( false !== $from_hook ); if ( self::$rendered ) { return; } $screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null; if ( ! $screen || empty( $screen->id ) ) { return; } foreach ( self::$plugins as $id => $config ) { if ( ! current_user_can( $config['capability'] ) ) { continue; } if ( 'show' !== get_option( $config['option'] ) ) { continue; } if ( ! in_array( $screen->id, (array) $config['screens'], true ) ) { continue; } if ( $from_hook && in_array( $screen->id, (array) $config['defer_screens'], true ) ) { continue; } self::cpfm_render( $config, $screen ); self::$rendered = true; return; } } /** * Host-supplied string with a developer-English fallback. * * @param array $config Plugin config. * @param string $key Copy key. * @param string $default Fallback. * @return string */ private static function cpfm_text( $config, $key, $default ) { if ( isset( $config['i18n'][ $key ] ) && is_string( $config['i18n'][ $key ] ) && '' !== $config['i18n'][ $key ] ) { return $config['i18n'][ $key ]; } return $default; } /** * Emit the notice. * * @param array $config Plugin config. * @param WP_Screen $screen Current screen. * @return void */ private static function cpfm_render( $config, $screen ) { $id = $config['id']; $action = 'cpfm_welcome_' . $id; $settings = $config['settings_url'] ? $config['settings_url'] : admin_url(); $explore = wp_nonce_url( add_query_arg( 'cpfm-welcome', $id, $settings ), $action ); $dismiss = wp_nonce_url( add_query_arg( 'cpfm-welcome', $id ), $action ); $inline = in_array( $screen->id, (array) $config['inline_screens'], true ) ? ' inline' : ''; ?>