sureforms / admin / notice-manager.php

notice-manager.php in SureForms – Contact Form Builder, AI Forms, Payment Form, Survey & Quiz 2.7.0, at admin/notice-manager.php

208 lines 5.7 KB

Raw Download Zip

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 (can contain HTML).
62	* @type string $title Optional. Notice title.
63	* @type array $actions Optional. Array of action button configurations.
64	* @type bool $dismissible Optional. Whether notice can be dismissed. Default true.
65	* @type array $pages Optional. Page slugs where notice should appear. Default ['all'].
66	* }
67	*
68	* Action button structure:
69	* {
70	* @type string $label Required. Button text.
71	* @type string $url Optional. URL to navigate to.
72	* @type string $target Optional. Link target: '_blank' or '_self'. Default '_self'.
73	* @type string $variant Optional. Button variant: 'primary', 'secondary', 'link'. Default 'primary'.
74	* @type string $size Optional. Button size: 'sm', 'md', 'lg'. Default 'sm'.
75	* @type string $className Optional. Additional CSS classes.
76	* }
77	*
78	* @return void
79	* @since 2.5.0
80	*/
81	public static function register_notice( $notice_args ) {
82	// Validate required fields.
83	if ( empty( $notice_args['id'] ) \|\| empty( $notice_args['message'] ) ) {
84	return;
85	}
86
87	// Set defaults.
88	$notice = wp_parse_args(
89	$notice_args,
90	[
91	'id' => '',
92	'variant' => 'info',
93	'message' => '',
94	'title' => '',
95	'actions' => [],
96	'dismissible' => true,
97	'pages' => [ 'all' ],
98	]
99	);
100
101	// Ensure pages is an array.
102	if ( ! is_array( $notice['pages'] ) ) {
103	$notice['pages'] = [ $notice['pages'] ];
104	}
105
106	// Store the notice.
107	self::$notices[ $notice['id'] ] = $notice;
108	}
109
110	/**
111	* Get all registered notices.
112	*
113	* @return array Array of notice configurations.
114	* @since 2.5.0
115	*/
116	public static function get_notices() {
117	return array_values( self::$notices );
118	}
119
120	/**
121	* Remove a registered notice.
122	*
123	* @param string $notice_id The notice ID to remove.
124	* @return void
125	* @since 2.5.0
126	*/
127	public static function remove_notice( $notice_id ) {
128	if ( isset( self::$notices[ $notice_id ] ) ) {
129	unset( self::$notices[ $notice_id ] );
130	}
131	}
132
133	/**
134	* Clear all registered notices.
135	*
136	* @return void
137	* @since 2.5.0
138	*/
139	public static function clear_notices() {
140	self::$notices = [];
141	}
142
143	/**
144	* Add notices to localized data for React.
145	*
146	* This filter callback adds the notices array to the localized script data
147	* that gets passed to React via window.srfm_admin.
148	*
149	* @param array $localization_data Existing localization data.
150	* @return array Modified localization data with notices.
151	* @since 2.5.0
152	*/
153	public function add_notices_to_localized_data( $localization_data ) {
154	$localization_data['notices'] = self::get_notices();
155	return $localization_data;
156	}
157
158	/**
159	* Helper method to register a notice from existing PHP admin_notices hooks.
160	*
161	* This method simplifies converting existing PHP notices to work with React.
162	* Call this method from your existing admin_notices callback to also register
163	* the notice for React pages.
164	*
165	* Example usage:
166	* ```php
167	* public function my_admin_notice() {
168	* $message = '<p>' . esc_html__( 'Important notice!', 'sureforms' ) . '</p>';
169	*
170	* // Display in PHP (existing behavior - continues to work)
171	* echo '<div class="notice notice-error">' . wp_kses_post( $message ) . '</div>';
172	*
173	* // Also register for React pages (new behavior)
174	* Notice_Manager::register_from_php_notice(
175	* 'my-notice-id',
176	* 'error',
177	* $message,
178	* [
179	* [
180	* 'label' => __( 'Fix Now', 'sureforms' ),
181	* 'url' => admin_url( 'admin.php?page=settings' ),
182	* ]
183	* ]
184	* );
185	* }
186	* ```
187	*
188	* @param string $id Unique notice identifier.
189	* @param string $variant Notice type: 'error', 'warning', 'info', 'success'.
190	* @param string $message Notice message (HTML allowed).
191	* @param array $actions Optional. Array of action button configurations.
192	* @param array $pages Optional. Page slugs where notice should appear. Default ['all'].
193	* @return void
194	* @since 2.5.0
195	*/
196	public static function register_from_php_notice( $id, $variant, $message, $actions = [], $pages = [ 'all' ] ) {
197	self::register_notice(
198	[
199	'id' => $id,
200	'variant' => $variant,
201	'message' => $message,
202	'actions' => $actions,
203	'pages' => $pages,
204	]
205	);
206	}
207	}
208