suredonation / inc / admin / notice-manager.php

notice-manager.php in SureDonation – Donation Forms, Fundraising Campaigns & Donor Management 1.6.0, at inc/admin/notice-manager.php

155 lines 4.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Admin Notice Manager Class.
4	*
5	* Bridges PHP-registered admin notices into the SureDonation React admin app.
6	* PHP code registers notices via Notice_Manager::register_notice(); this class
7	* injects them into the localized `suredonation_admin` global (through the
8	* `suredonation_admin_app_data` filter) so the React AdminNotice component can
9	* render them on the SPA pages.
10	*
11	* @package SureDonation
12	* @since 1.3.0
13	*/
14
15	namespace SureDonation\Inc\Admin;
16
17	use SureDonation\Inc\Traits\Get_Instance;
18
19	// Exit if accessed directly.
20	if ( ! defined( 'ABSPATH' ) ) {
21	exit;
22	}
23
24	/**
25	* Notice Manager class.
26	*
27	* Handles collection and distribution of admin notices to the React admin app.
28	*
29	* @since 1.3.0
30	*/
31	class Notice_Manager {
32	use Get_Instance;
33
34	/**
35	* Registered notices, keyed by notice id.
36	*
37	* @var array<string, array<string, mixed>>
38	* @since 1.3.0
39	*/
40	private static $notices = [];
41
42	/**
43	* Constructor.
44	*
45	* @since 1.3.0
46	* @return void
47	*/
48	public function __construct() {
49	// Inject registered notices into the React app's localized data.
50	add_filter( 'suredonation_admin_app_data', [ $this, 'add_notices_to_localized_data' ] );
51	}
52
53	/**
54	* Register a notice for display in the React admin pages.
55	*
56	* @param array<string, mixed> $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. May contain a single <a>…</a> marker
62	* whose text/position is used for the inline link (see $link).
63	* @type string $title Optional. Notice title.
64	* @type array $link Optional. Inline link for the <a> marker: [ 'url' => string, 'target' => '_self'\|'_blank' ].
65	* @type string $event Optional. Analytics event name fired when the notice's inline link is clicked.
66	* @type array $actions Optional. Trailing action buttons, used only when $link is absent.
67	* @type bool $dismissible Optional. Reserved; dismissal is not yet wired in the React renderer. Default true.
68	* }
69	*
70	* Action button structure (trailing fallback):
71	* {
72	* @type string $label Required. Button text.
73	* @type string $url Optional. URL to navigate to on click.
74	* @type string $target Optional. Link target: '_blank' or '_self'. Default '_self'.
75	* }
76	*
77	* @since 1.3.0
78	* @return void
79	*/
80	public static function register_notice( $notice_args ) {
81	// Validate required fields.
82	if ( empty( $notice_args['id'] ) \|\| empty( $notice_args['message'] ) ) {
83	return;
84	}
85
86	// Set defaults.
87	$notice = wp_parse_args(
88	$notice_args,
89	[
90	'id' => '',
91	'variant' => 'info',
92	'message' => '',
93	'title' => '',
94	'link' => null,
95	'event' => '',
96	'actions' => [],
97	'dismissible' => true,
98	]
99	);
100
101	// Store the notice.
102	self::$notices[ $notice['id'] ] = $notice;
103	}
104
105	/**
106	* Get all registered notices.
107	*
108	* @since 1.3.0
109	* @return array<int, array<string, mixed>> Array of notice configurations.
110	*/
111	public static function get_notices() {
112	return array_values( self::$notices );
113	}
114
115	/**
116	* Remove a registered notice.
117	*
118	* @param string $notice_id The notice ID to remove.
119	* @since 1.3.0
120	* @return void
121	*/
122	public static function remove_notice( $notice_id ) {
123	if ( isset( self::$notices[ $notice_id ] ) ) {
124	unset( self::$notices[ $notice_id ] );
125	}
126	}
127
128	/**
129	* Clear all registered notices.
130	*
131	* @since 1.3.0
132	* @return void
133	*/
134	public static function clear_notices() {
135	self::$notices = [];
136	}
137
138	/**
139	* Add the registered notices to the React app's localized data.
140	*
141	* Hooked - suredonation_admin_app_data
142	*
143	* @param array<string, mixed> $localization_data Existing localization data.
144	* @since 1.3.0
145	* @return array<string, mixed> Modified localization data with notices.
146	*/
147	public function add_notices_to_localized_data( $localization_data ) {
148	if ( ! is_array( $localization_data ) ) {
149	return $localization_data;
150	}
151	$localization_data['notices'] = self::get_notices();
152	return $localization_data;
153	}
154	}
155