Notification.php — WooCommerce 10.9.1

woocommerce / src / Internal / PushNotifications / Notifications / Notification.php

woocommerce / src / Internal / PushNotifications / Notifications Last commit date

NewOrderNotification.php 4 weeks ago NewReviewNotification.php 4 weeks ago Notification.php 4 weeks ago StockNotification.php 4 weeks ago

Notification.php

237 lines

1	<?php
2
3	declare( strict_types = 1 );
4
5	namespace Automattic\WooCommerce\Internal\PushNotifications\Notifications;
6
7	use InvalidArgumentException;
8
9	defined( 'ABSPATH' ) \|\| exit;
10
11	/**
12	* Base class for push notifications.
13	*
14	* Each notification type (e.g. new order, new review) extends this class
15	* and implements `to_payload()` with its own title, message, icon, and meta.
16	*
17	* @since 10.7.0
18	*/
19	abstract class Notification {
20	/**
21	* Map of notification type identifiers to their corresponding subclass.
22	*
23	* @var array<string, class-string<Notification>>
24	*/
25	const NOTIFICATION_CLASSES = array(
26	'store_order' => NewOrderNotification::class,
27	'store_review' => NewReviewNotification::class,
28	'store_stock' => StockNotification::class,
29	);
30
31	/**
32	* The ID of the resource this notification is about (e.g. order ID, comment
33	* ID).
34	*
35	* @var int
36	*/
37	private int $resource_id;
38
39	/**
40	* Creates a new Notification instance.
41	*
42	* @param int $resource_id The resource ID.
43	*
44	* @throws InvalidArgumentException If the resource ID is invalid.
45	*
46	* @since 10.7.0
47	*/
48	public function __construct( int $resource_id ) {
49	if ( $resource_id <= 0 ) {
50	throw new InvalidArgumentException( 'Notification resource_id must be positive.' );
51	}
52
53	$this->resource_id = $resource_id;
54	}
55
56	/**
57	* Returns the notification type identifier, this should match the subtype
58	* or type (if there isn't a subtype) values attributed to notes in
59	* WordPress.com.
60	*
61	* @return string
62	*
63	* @since 10.7.0
64	*/
65	abstract public function get_type(): string;
66
67	/**
68	* Returns the WPCOM-ready payload for this notification.
69	*
70	* Returns null if the underlying resource no longer exists.
71	*
72	* @return array\|null
73	*
74	* @since 10.7.0
75	*/
76	abstract public function to_payload(): ?array;
77
78	/**
79	* Checks whether a meta key exists for this notification's resource.
80	*
81	* @param string $key The meta key.
82	* @return bool
83	*
84	* @since 10.7.0
85	*/
86	abstract public function has_meta( string $key ): bool;
87
88	/**
89	* Writes a meta key with a timestamp to this notification's resource.
90	*
91	* @param string $key The meta key.
92	* @return void
93	*
94	* @since 10.7.0
95	*/
96	abstract public function write_meta( string $key ): void;
97
98	/**
99	* Deletes a meta key from this notification's resource.
100	*
101	* @param string $key The meta key.
102	* @return void
103	*
104	* @since 10.8.0
105	*/
106	abstract public function delete_meta( string $key ): void;
107
108	/**
109	* Returns the notification data as an array.
110	*
111	* @return array{type: string, resource_id: int}
112	*
113	* @since 10.7.0
114	*/
115	public function to_array(): array {
116	return array(
117	'type' => $this->get_type(),
118	'resource_id' => $this->resource_id,
119	);
120	}
121
122	/**
123	* Reconstructs a Notification subclass from a serialized array.
124	*
125	* @param array{type: string, resource_id: int} $data The notification data.
126	* @return self
127	*
128	* @throws InvalidArgumentException If the type is unknown.
129	*
130	* @since 10.7.0
131	*/
132	public static function from_array( array $data ): self {
133	$type = $data['type'] ?? '';
134	$resource_id = (int) ( $data['resource_id'] ?? 0 );
135
136	$class = self::NOTIFICATION_CLASSES[ $type ] ?? null;
137
138	if ( ! $class ) {
139	// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
140	throw new InvalidArgumentException( sprintf( 'Unknown notification type: %s', $type ) );
141	}
142
143	$instance = new $class( $resource_id );
144
145	if ( method_exists( $instance, 'hydrate' ) ) {
146	$instance->hydrate( $data );
147	}
148
149	return $instance;
150	}
151
152	/**
153	* Returns a unique identifier for this notification, used for
154	* deduplication.
155	*
156	* @return string
157	*
158	* @since 10.7.0
159	*/
160	public function get_identifier(): string {
161	return sprintf( '%s_%s_%s', get_current_blog_id(), $this->get_type(), $this->resource_id );
162	}
163
164	/**
165	* Gets the resource ID.
166	*
167	* @return int
168	*
169	* @since 10.7.0
170	*/
171	public function get_resource_id(): int {
172	return $this->resource_id;
173	}
174
175	/**
176	* Canonical positional ActionScheduler arguments for the safety-net job.
177	*
178	* Single source of truth shared by the scheduler (and its dedupe guard) and
179	* the cancel path so the serialized args always match. Action Scheduler
180	* matches the stored args by exact equality, so any divergence between the
181	* schedule-side and cancel-side shapes silently breaks cancellation.
182	*
183	* The args are keyed on the notification's identity — the minimal data
184	* needed to uniquely identify and reconstruct the notification — mirroring
185	* {@see self::get_identifier()}. Volatile payload fields (e.g. a stock
186	* snapshot captured at trigger time) must not be included: they are not part
187	* of the identity and may differ between schedule and cancel.
188	*
189	* @return array<int, mixed>
190	*
191	* @since 10.9.0
192	*/
193	public function get_safety_net_args(): array {
194	return array( $this->get_type(), $this->get_resource_id() );
195	}
196
197	/**
198	* Decide whether this notification should be delivered to a user given
199	* their stored preference value for {@see static::get_type()}.
200	*
201	* `$pref_value` is whatever the user has stored under this notification
202	* type's preference key, or `null` if they have nothing stored. The
203	* {@see NotificationPreferencesService} stores each preference as an
204	* object so future sub-fields (thresholds, sub-toggles) can be added
205	* without bumping the schema version — today's shape is
206	* `['enabled' => bool]`, future shapes might add e.g.
207	* `['enabled' => true, 'min_value' => 500]` for an order threshold.
208	*
209	* Default: read the universal `enabled` sub-field, defaulting to `true`
210	* when the value is missing or has no `enabled` key (so newly-added
211	* notification types are opt-in by default). Subclasses override to
212	* read richer sub-fields and to consult their own resource (e.g.
213	* compare an order total to the user's `min_value`).
214	*
215	* Subclasses must keep this side-effect-free — the {@see NotificationProcessor}
216	* may call it once per recipient user per notification.
217	*
218	* @param mixed $pref_value The user's stored preference value, or null.
219	* @return bool True if this notification should be sent to that user.
220	*
221	* @since 10.9.0
222	*/
223	public function should_send_to_user( $pref_value ): bool {
224	if ( null === $pref_value ) {
225	return true;
226	}
227
228	if ( is_array( $pref_value ) ) {
229	return (bool) ( $pref_value['enabled'] ?? true );
230	}
231
232	// Defensive fallback for unexpected scalar values; the service
233	// always normalises stored prefs to the array shape above.
234	return (bool) $pref_value;
235	}
236	}
237