notice-manager.php
217 lines
| 1 | <?php |
| 2 | /** |
| 3 | * Admin Notice Manager Class. |
| 4 | * |
| 5 | * This class manages admin notices and bridges them to React admin pages. |
| 6 | * It collects notices from various sources (including existing PHP notices) |
| 7 | * and exports them to React via wp_localize_script. |
| 8 | * |
| 9 | * @package sureforms |
| 10 | * @since 2.5.0 |
| 11 | */ |
| 12 | |
| 13 | namespace SRFM\Admin; |
| 14 | |
| 15 | use SRFM\Inc\Traits\Get_Instance; |
| 16 | |
| 17 | if ( ! defined( 'ABSPATH' ) ) { |
| 18 | exit; // Exit if accessed directly. |
| 19 | } |
| 20 | |
| 21 | /** |
| 22 | * Notice Manager class. |
| 23 | * |
| 24 | * Handles collection and distribution of admin notices to both PHP and React contexts. |
| 25 | * |
| 26 | * @since 2.5.0 |
| 27 | */ |
| 28 | class Notice_Manager { |
| 29 | use Get_Instance; |
| 30 | |
| 31 | /** |
| 32 | * Registered notices. |
| 33 | * |
| 34 | * @var array |
| 35 | * @since 2.5.0 |
| 36 | */ |
| 37 | private static $notices = []; |
| 38 | |
| 39 | /** |
| 40 | * Class constructor. |
| 41 | * |
| 42 | * @return void |
| 43 | * @since 2.5.0 |
| 44 | */ |
| 45 | public function __construct() { |
| 46 | // Hook to add notices to localized data. |
| 47 | add_filter( 'srfm_admin_filter', [ $this, 'add_notices_to_localized_data' ] ); |
| 48 | } |
| 49 | |
| 50 | /** |
| 51 | * Register a notice for display in React admin pages. |
| 52 | * |
| 53 | * This method allows PHP code to register notices that will be displayed |
| 54 | * in React admin pages via the AdminNotice component. |
| 55 | * |
| 56 | * @param array $notice_args { |
| 57 | * Notice configuration arguments. |
| 58 | * |
| 59 | * @type string $id Required. Unique notice identifier. |
| 60 | * @type string $variant Notice type: 'error', 'warning', 'info', 'success'. Default 'info'. |
| 61 | * @type string $message Required. Notice message. Plain text only — |
| 62 | * AdminNotice.js renders it as a React child, so any |
| 63 | * markup shows up as literal characters. Links belong |
| 64 | * in `actions`. |
| 65 | * @type string $title Optional. Notice title. |
| 66 | * @type array $actions Optional. Array of action button configurations. |
| 67 | * @type bool $dismissible Optional. Whether notice can be dismissed. Default true. |
| 68 | * @type array $pages Optional. Page slugs where notice should appear. Default ['all']. |
| 69 | * } |
| 70 | * |
| 71 | * Action button structure: |
| 72 | * { |
| 73 | * @type string $label Required. Button text. |
| 74 | * @type string $url Optional. URL to navigate to. |
| 75 | * @type string $target Optional. Link target: '_blank' or '_self'. Default '_self'. |
| 76 | * @type string $variant Optional. Button variant: 'primary', 'secondary', 'link'. Default 'primary'. |
| 77 | * @type string $size Optional. Button size: 'sm', 'md', 'lg'. Default 'sm'. |
| 78 | * @type string $className Optional. Additional CSS classes. |
| 79 | * @type string $action Optional. Opaque identifier that AdminNotice.js resolves |
| 80 | * to a local handler, for an action that must call the |
| 81 | * server. Deliberately NOT a URL, endpoint or HTTP method: |
| 82 | * the server never tells the browser which address to call. |
| 83 | * Pair it with `url` so the action still does something if |
| 84 | * no handler is registered for the identifier. |
| 85 | * } |
| 86 | * |
| 87 | * @return void |
| 88 | * @since 2.5.0 |
| 89 | */ |
| 90 | public static function register_notice( $notice_args ) { |
| 91 | // Validate required fields. |
| 92 | if ( empty( $notice_args['id'] ) || empty( $notice_args['message'] ) ) { |
| 93 | return; |
| 94 | } |
| 95 | |
| 96 | // Set defaults. |
| 97 | $notice = wp_parse_args( |
| 98 | $notice_args, |
| 99 | [ |
| 100 | 'id' => '', |
| 101 | 'variant' => 'info', |
| 102 | 'message' => '', |
| 103 | 'title' => '', |
| 104 | 'actions' => [], |
| 105 | 'dismissible' => true, |
| 106 | 'pages' => [ 'all' ], |
| 107 | ] |
| 108 | ); |
| 109 | |
| 110 | // Ensure pages is an array. |
| 111 | if ( ! is_array( $notice['pages'] ) ) { |
| 112 | $notice['pages'] = [ $notice['pages'] ]; |
| 113 | } |
| 114 | |
| 115 | // Store the notice. |
| 116 | self::$notices[ $notice['id'] ] = $notice; |
| 117 | } |
| 118 | |
| 119 | /** |
| 120 | * Get all registered notices. |
| 121 | * |
| 122 | * @return array Array of notice configurations. |
| 123 | * @since 2.5.0 |
| 124 | */ |
| 125 | public static function get_notices() { |
| 126 | return array_values( self::$notices ); |
| 127 | } |
| 128 | |
| 129 | /** |
| 130 | * Remove a registered notice. |
| 131 | * |
| 132 | * @param string $notice_id The notice ID to remove. |
| 133 | * @return void |
| 134 | * @since 2.5.0 |
| 135 | */ |
| 136 | public static function remove_notice( $notice_id ) { |
| 137 | if ( isset( self::$notices[ $notice_id ] ) ) { |
| 138 | unset( self::$notices[ $notice_id ] ); |
| 139 | } |
| 140 | } |
| 141 | |
| 142 | /** |
| 143 | * Clear all registered notices. |
| 144 | * |
| 145 | * @return void |
| 146 | * @since 2.5.0 |
| 147 | */ |
| 148 | public static function clear_notices() { |
| 149 | self::$notices = []; |
| 150 | } |
| 151 | |
| 152 | /** |
| 153 | * Add notices to localized data for React. |
| 154 | * |
| 155 | * This filter callback adds the notices array to the localized script data |
| 156 | * that gets passed to React via window.srfm_admin. |
| 157 | * |
| 158 | * @param array $localization_data Existing localization data. |
| 159 | * @return array Modified localization data with notices. |
| 160 | * @since 2.5.0 |
| 161 | */ |
| 162 | public function add_notices_to_localized_data( $localization_data ) { |
| 163 | $localization_data['notices'] = self::get_notices(); |
| 164 | return $localization_data; |
| 165 | } |
| 166 | |
| 167 | /** |
| 168 | * Helper method to register a notice from existing PHP admin_notices hooks. |
| 169 | * |
| 170 | * This method simplifies converting existing PHP notices to work with React. |
| 171 | * Call this method from your existing admin_notices callback to also register |
| 172 | * the notice for React pages. |
| 173 | * |
| 174 | * Example usage: |
| 175 | * ```php |
| 176 | * public function my_admin_notice() { |
| 177 | * $message = '<p>' . esc_html__( 'Important notice!', 'sureforms' ) . '</p>'; |
| 178 | * |
| 179 | * // Display in PHP (existing behavior - continues to work) |
| 180 | * echo '<div class="notice notice-error">' . wp_kses_post( $message ) . '</div>'; |
| 181 | * |
| 182 | * // Also register for React pages (new behavior) |
| 183 | * Notice_Manager::register_from_php_notice( |
| 184 | * 'my-notice-id', |
| 185 | * 'error', |
| 186 | * $message, |
| 187 | * [ |
| 188 | * [ |
| 189 | * 'label' => __( 'Fix Now', 'sureforms' ), |
| 190 | * 'url' => admin_url( 'admin.php?page=settings' ), |
| 191 | * ] |
| 192 | * ] |
| 193 | * ); |
| 194 | * } |
| 195 | * ``` |
| 196 | * |
| 197 | * @param string $id Unique notice identifier. |
| 198 | * @param string $variant Notice type: 'error', 'warning', 'info', 'success'. |
| 199 | * @param string $message Notice message. Plain text only; see register_notice(). |
| 200 | * @param array $actions Optional. Array of action button configurations. |
| 201 | * @param array $pages Optional. Page slugs where notice should appear. Default ['all']. |
| 202 | * @return void |
| 203 | * @since 2.5.0 |
| 204 | */ |
| 205 | public static function register_from_php_notice( $id, $variant, $message, $actions = [], $pages = [ 'all' ] ) { |
| 206 | self::register_notice( |
| 207 | [ |
| 208 | 'id' => $id, |
| 209 | 'variant' => $variant, |
| 210 | 'message' => $message, |
| 211 | 'actions' => $actions, |
| 212 | 'pages' => $pages, |
| 213 | ] |
| 214 | ); |
| 215 | } |
| 216 | } |
| 217 |