← All changes | includes/seen-intros.php +123 -62 0.9.8 → 1.1.12 View file →

		@@ -1,36 +1,47 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — "Seen intros" registry.
	3	+ * OpenStation — "Seen intros" registry.
4	4	*
5		- * Tracks which one-time introduction dialogs the current user has
6		- * already dismissed, so the shell can show a "what's new in this
7		- * native app" dialog the first time a ported native window opens
8		- * and never bother the user again afterwards.
	5	+ * Tracks which one-time announcements the current user has already
	6	+ * dismissed, so each is shown once and never bothers them again.
9	7	*
10		- * Today the surface is the native Posts window. The same key is
11		- * intentionally generic — any future ported native app (Pages,
12		- * Comments, Users, Plugins, …) registers its own slug and reuses
13		- * this storage. OS Settings → Features exposes a "Reset what's-new
14		- * dialogs" button that clears the whole list so the user can see
15		- * every intro again from scratch.
	8	+ * Three surfaces use it today: the activation welcome dialog
	9	+ * (`includes/welcome-dialog.php`, slug `activation-welcome`), shown
	10	+ * in the classic admin while OpenStation is disabled, the rebrand
	11	+ * notice (`src/rebrand-notice.ts`, slug `openstation-rebrand`), and
	12	+ * the usage feedback prompt (`includes/feedback/usage.php`, slug
	13	+ * `usage-feedback`, marked server-side on a successful send). The
	14	+ * key is intentionally generic, so anything else that needs
	15	+ * show-once semantics registers its own slug and reuses this storage.
	16	+ * OpenStation Preferences → Features exposes a "Reset what's-new
	17	+ * dialogs" button that clears the whole list.
16	18	*
17	19	* Storage shape:
18	20	* user meta `desktop_mode_seen_intros` → array<string> of slugs.
19		- * `[ 'posts' ]`, `[ 'posts', 'pages' ]`, etc. Slug values pass
20		- * through `sanitize_key()` and the list is capped at 64 entries
21		- * so a runaway client cannot bloat user-meta indefinitely.
	21	+ * `[ 'activation-welcome' ]`, `[ 'openstation-rebrand' ]`, etc.
	22	+ * Slug values pass through `sanitize_key()` and the list is capped
	23	+ * at 64 entries so a runaway client cannot bloat user-meta
	24	+ * indefinitely.
22	25	*
23		- * @package WPDesktopMode
	26	+ * @package OpenStation
24	27	*/
25	28
26	29	defined( 'ABSPATH' ) || exit;
27	30
28		-/** User meta key — see file header for shape. */
29		-const DESKTOP_MODE_SEEN_INTROS_META_KEY = 'desktop_mode_seen_intros';
	31	+/**
	32	+ * User meta key — see file header for shape.
	33	+ *
	34	+ * The VALUE keeps its pre-rebrand spelling on purpose: it is a
	35	+ * persisted or externally-visible identifier, so renaming it would
	36	+ * orphan data already written by live installs (or break a live
	37	+ * URL). The mismatch between this constant's name and its value is
	38	+ * deliberate — it is NOT a half-finished rename.
	39	+ */
	40	+const OPENSTATION_SEEN_INTROS_META_KEY = 'desktop_mode_seen_intros';
30	41
31	42	/** Hard cap so a malicious client cannot grow the list unbounded. */
32		-const DESKTOP_MODE_SEEN_INTROS_MAX = 64;
	43	+const OPENSTATION_SEEN_INTROS_MAX = 64;
33	44
34	45	/**
35	46	* Returns the list of intro slugs the user has dismissed.
36	47	*
		@@ -36,20 +47,20 @@
36	47	*
37	48	* @param int $user_id User ID.
38	49	* @return string[] Sanitized list (may be empty).
39	50	*/
40		-function desktop_mode_get_seen_intros( $user_id ) {
	51	+function openstation_get_seen_intros( $user_id ) {
41	52	$user_id = (int) $user_id;
42	53	if ( $user_id <= 0 ) {
43	54	return array();
44	55	}
45	56
46		- $raw = get_user_meta( $user_id, DESKTOP_MODE_SEEN_INTROS_META_KEY, true );
	57	+ $raw = get_user_meta( $user_id, OPENSTATION_SEEN_INTROS_META_KEY, true );
47	58	if ( ! is_array( $raw ) ) {
48	59	return array();
49	60	}
50	61
51		- return desktop_mode_sanitize_seen_intros( $raw );
	62	+ return openstation_sanitize_seen_intros( $raw );
52	63	}
53	64
54	65	/**
55	66	* Whether the user has already dismissed the given intro.
		@@ -57,14 +68,14 @@
57	68	* @param int $user_id User ID.
58	69	* @param string $slug Intro slug (e.g. `'posts'`).
59	70	* @return bool
60	71	*/
61		-function desktop_mode_has_seen_intro( $user_id, $slug ) {
	72	+function openstation_has_seen_intro( $user_id, $slug ) {
62	73	$slug = sanitize_key( (string) $slug );
63	74	if ( '' === $slug ) {
64	75	return false;
65	76	}
66		- return in_array( $slug, desktop_mode_get_seen_intros( $user_id ), true );
	77	+ return in_array( $slug, openstation_get_seen_intros( $user_id ), true );
67	78	}
68	79
69	80	/**
70	81	* Adds a slug to the user's seen-intros list.
		@@ -69,15 +80,16 @@
69	80	/**
70	81	* Adds a slug to the user's seen-intros list.
71	82	*
72	83	* Idempotent — re-marking an already-seen intro is a no-op that
73		- * still returns true.
	84	+ * still returns true. A slug that supersedes others
	85	+ * ({@see openstation_seen_intros_superseded_by()}) removes them first.
74	86	*
75	87	* @param int $user_id User ID.
76	88	* @param string $slug Intro slug.
77	89	* @return bool True on successful write (or no-op), false otherwise.
78	90	*/
79		-function desktop_mode_mark_intro_seen( $user_id, $slug ) {
	91	+function openstation_mark_intro_seen( $user_id, $slug ) {
80	92	$user_id = (int) $user_id;
81	93	$slug = sanitize_key( (string) $slug );
82	94	if ( $user_id <= 0 || '' === $slug ) {
83	95	return false;
		@@ -82,24 +94,48 @@
82	94	if ( $user_id <= 0 || '' === $slug ) {
83	95	return false;
84	96	}
85	97
86		- $current = desktop_mode_get_seen_intros( $user_id );
87		- if ( in_array( $slug, $current, true ) ) {
	98	+ $current = openstation_get_seen_intros( $user_id );
	99	+ $kept = array_values( array_diff( $current, openstation_seen_intros_superseded_by( $slug ) ) );
	100	+ if ( in_array( $slug, $kept, true ) && count( $kept ) === count( $current ) ) {
88	101	return true;
89	102	}
90	103
91		- $current[] = $slug;
92		- $current = array_slice( $current, 0, DESKTOP_MODE_SEEN_INTROS_MAX );
	104	+ if ( ! in_array( $slug, $kept, true ) ) {
	105	+ $kept[] = $slug;
	106	+ }
	107	+ $kept = array_slice( $kept, 0, OPENSTATION_SEEN_INTROS_MAX );
93	108
94	109	return false !== update_user_meta(
95	110	$user_id,
96		- DESKTOP_MODE_SEEN_INTROS_META_KEY,
97		- $current
	111	+ OPENSTATION_SEEN_INTROS_META_KEY,
	112	+ $kept
98	113	);
99	114	}
100	115
101	116	/**
	117	+ * Slugs a newly recorded one makes obsolete: facts where only the
	118	+ * latest counts, which an append-only list cannot otherwise express.
	119	+ *
	120	+ * The shell tour's two outcomes are the one pair. A run ends skipped
	121	+ * or finished, and the relaunch icon asks about the LATEST run: kept
	122	+ * side by side, one finished run long ago hid the icon after every
	123	+ * skip that came later. The strings mirror the constants in
	124	+ * `includes/first-run/shell-tour.php`, which loads after this file.
	125	+ *
	126	+ * @param string $slug The slug being recorded.
	127	+ * @return string[] Slugs it replaces.
	128	+ */
	129	+function openstation_seen_intros_superseded_by( $slug ) {
	130	+ $pairs = array(
	131	+ 'shell-tour-skipped' => array( 'shell-tour-done' ),
	132	+ 'shell-tour-done' => array( 'shell-tour-skipped' ),
	133	+ );
	134	+ return isset( $pairs[ $slug ] ) ? $pairs[ $slug ] : array();
	135	+}
	136	+
	137	+/**
102	138	* Wipes every seen-intro entry for the user. Used by the OS
103	139	* Settings → Features "Reset what's-new dialogs" button.
104	140	*
105	141	* @param int $user_id User ID.
		@@ -104,14 +140,14 @@
104	140	*
105	141	* @param int $user_id User ID.
106	142	* @return bool True on success.
107	143	*/
108		-function desktop_mode_clear_seen_intros( $user_id ) {
	144	+function openstation_clear_seen_intros( $user_id ) {
109	145	$user_id = (int) $user_id;
110	146	if ( $user_id <= 0 ) {
111	147	return false;
112	148	}
113		- return (bool) delete_user_meta( $user_id, DESKTOP_MODE_SEEN_INTROS_META_KEY );
	149	+ return (bool) delete_user_meta( $user_id, OPENSTATION_SEEN_INTROS_META_KEY );
114	150	}
115	151
116	152	/**
117	153	* Coerces a raw payload to a clean list of slugs.
		@@ -118,9 +154,9 @@
118	154	*
119	155	* @param mixed $raw Raw value.
120	156	* @return string[]
121	157	*/
122		-function desktop_mode_sanitize_seen_intros( $raw ) {
	158	+function openstation_sanitize_seen_intros( $raw ) {
123	159	if ( ! is_array( $raw ) ) {
124	160	return array();
125	161	}
126	162	$out = array();
		@@ -133,9 +169,9 @@
133	169	continue;
134	170	}
135	171	$out[] = $slug;
136	172	}
137		- return array_slice( array_values( array_unique( $out ) ), 0, DESKTOP_MODE_SEEN_INTROS_MAX );
	173	+ return array_slice( array_values( array_unique( $out ) ), 0, OPENSTATION_SEEN_INTROS_MAX );
138	174	}
139	175
140	176	/**
141	177	* Registers REST routes for the seen-intros surface.
		@@ -146,16 +182,16 @@
146	182	*
147	183	* Both return the post-mutation list so the client can refresh its
148	184	* local snapshot without a follow-up GET.
149	185	*/
150		-function desktop_mode_register_seen_intros_routes() {
	186	+function openstation_register_seen_intros_routes() {
151	187	register_rest_route(
152	188	'desktop-mode/v1',
153	189	'/intros/seen',
154	190	array(
155	191	'methods' => WP_REST_Server::CREATABLE,
156		- 'callback' => 'desktop_mode_rest_mark_intro_seen',
157		- 'permission_callback' => 'desktop_mode_rest_seen_intros_permission',
	192	+ 'callback' => 'openstation_rest_mark_intro_seen',
	193	+ 'permission_callback' => 'openstation_rest_seen_intros_permission',
158	194	'args' => array(
159	195	'slug' => array(
160	196	'required' => true,
161	197	'type' => 'string',
		@@ -168,32 +204,57 @@
168	204	'desktop-mode/v1',
169	205	'/intros',
170	206	array(
171	207	'methods' => WP_REST_Server::DELETABLE,
172		- 'callback' => 'desktop_mode_rest_clear_seen_intros',
173		- 'permission_callback' => 'desktop_mode_rest_seen_intros_permission',
	208	+ 'callback' => 'openstation_rest_clear_seen_intros',
	209	+ 'permission_callback' => 'openstation_rest_seen_intros_permission',
174	210	)
175	211	);
176	212	}
177		-add_action( 'rest_api_init', 'desktop_mode_register_seen_intros_routes' );
	213	+add_action( 'rest_api_init', 'openstation_register_seen_intros_routes' );
178	214
179	215	/**
	216	+ * The intro slugs whose dismissal is accepted from an account that has
	217	+ * NOT enabled OpenStation.
	218	+ *
	219	+ * Exactly the intros that render in the classic admin while the shell
	220	+ * is off: the welcome dialog and the activation nudge. Everything else
	221	+ * is shown inside the shell and keeps the strict gate. Adding a slug
	222	+ * here is adding a classic-admin surface; the allowlist is the review
	223	+ * point, so keep it a literal list.
	224	+ *
	225	+ * @return string[]
	226	+ */
	227	+function openstation_seen_intros_classic_admin_slugs() {
	228	+ $slugs = array();
	229	+ if ( defined( 'OPENSTATION_WELCOME_INTRO_SLUG' ) ) {
	230	+ $slugs[] = OPENSTATION_WELCOME_INTRO_SLUG;
	231	+ }
	232	+ if ( defined( 'OPENSTATION_ACTIVATION_NUDGE_INTRO_SLUG' ) ) {
	233	+ $slugs[] = OPENSTATION_ACTIVATION_NUDGE_INTRO_SLUG;
	234	+ }
	235	+ return $slugs;
	236	+}
	237	+
	238	+/**
180	239	* Permission gate for the seen-intros routes.
181	240	*
182		- * In-shell intros (slug `posts`, `pages`, …) are only ever shown to a
183		- * user who has already entered Desktop Mode, so they keep the strict
184		- * {@see desktop_mode_rest_require_enabled()} gate — `read` alone is
	241	+ * In-shell announcements (the rebrand notice, and anything a plugin
	242	+ * registers) are only ever shown to a user who has already entered
	243	+ * OpenStation, so they keep the strict
	244	+ * {@see openstation_rest_require_enabled()} gate — `read` alone is
185	245	* insufficient (every role, Subscriber included, carries `read`).
186	246	*
187		- * The one exception is the first-run welcome dialog
188		- * ({@see DESKTOP_MODE_WELCOME_INTRO_SLUG}): it renders in the *classic*
189		- * admin precisely when Desktop Mode is NOT enabled, which is the only
190		- * state it ever appears in. Gating its dismissal behind
191		- * `desktop_mode_rest_require_enabled()` would make the dismissal POST
	247	+ * The exceptions are the classic-admin intros
	248	+ * ({@see openstation_seen_intros_classic_admin_slugs()}): the first-run
	249	+ * welcome dialog and the activation nudge both render in the *classic*
	250	+ * admin precisely when OpenStation is NOT enabled, which is the only
	251	+ * state they ever appear in. Gating their dismissal behind
	252	+ * `openstation_rest_require_enabled()` would make the dismissal POST
192	253	* return 403 every time, so the slug could never be recorded as seen and
193		- * the dialog re-rendered on every classic-admin page load. We therefore
194		- * let that single slug through for any logged-in `read`-capable account
195		- * (the exact audience the dialog is shown to); writing one's own
	254	+ * the dialog / notice re-rendered on every classic-admin page load. We
	255	+ * therefore let those slugs through for any logged-in `read`-capable
	256	+ * account (the exact audience they are shown to); writing one's own
196	257	* dismissal flag carries no privileged surface. The DELETE /intros route
197	258	* ("Reset what's-new dialogs") carries no slug and keeps the strict gate.
198	259	*
199	260	* @param WP_REST_Request $request The REST request.
		@@ -198,11 +259,11 @@
198	259	*
199	260	* @param WP_REST_Request $request The REST request.
200	261	* @return true|WP_Error
201	262	*/
202		-function desktop_mode_rest_seen_intros_permission( WP_REST_Request $request ) {
	263	+function openstation_rest_seen_intros_permission( WP_REST_Request $request ) {
203	264	$slug = sanitize_key( (string) $request->get_param( 'slug' ) );
204		- if ( defined( 'DESKTOP_MODE_WELCOME_INTRO_SLUG' ) && DESKTOP_MODE_WELCOME_INTRO_SLUG === $slug ) {
	265	+ if ( '' !== $slug && in_array( $slug, openstation_seen_intros_classic_admin_slugs(), true ) ) {
205	266	if ( ! is_user_logged_in() ) {
206	267	return new WP_Error(
207	268	'rest_forbidden',
208	269	__( 'Authentication required.', 'desktop-mode' ),
		@@ -218,9 +279,9 @@
218	279	}
219	280	return true;
220	281	}
221	282
222		- return desktop_mode_rest_require_enabled();
	283	+ return openstation_rest_require_enabled();
223	284	}
224	285
225	286	/**
226	287	* REST handler for `POST /desktop-mode/v1/intros/seen`.
		@@ -227,21 +288,21 @@
227	288	*
228	289	* @param WP_REST_Request $request REST request.
229	290	* @return WP_REST_Response|WP_Error
230	291	*/
231		-function desktop_mode_rest_mark_intro_seen( WP_REST_Request $request ) {
	292	+function openstation_rest_mark_intro_seen( WP_REST_Request $request ) {
232	293	$user_id = get_current_user_id();
233	294	$slug = sanitize_key( (string) $request->get_param( 'slug' ) );
234	295	if ( '' === $slug ) {
235	296	return new WP_Error(
236		- 'desktop_mode_invalid_intro_slug',
	297	+ 'openstation_invalid_intro_slug',
237	298	__( 'The `slug` parameter must be a non-empty string.', 'desktop-mode' ),
238	299	array( 'status' => 400 )
239	300	);
240	301	}
241		- desktop_mode_mark_intro_seen( $user_id, $slug );
	302	+ openstation_mark_intro_seen( $user_id, $slug );
242	303	return rest_ensure_response(
243		- array( 'seenIntros' => desktop_mode_get_seen_intros( $user_id ) )
	304	+ array( 'seenIntros' => openstation_get_seen_intros( $user_id ) )
244	305	);
245	306	}
246	307
247	308	/**
		@@ -248,11 +309,11 @@
248	309	* REST handler for `DELETE /desktop-mode/v1/intros`.
249	310	*
250	311	* @return WP_REST_Response
251	312	*/
252		-function desktop_mode_rest_clear_seen_intros() {
	313	+function openstation_rest_clear_seen_intros() {
253	314	$user_id = get_current_user_id();
254		- desktop_mode_clear_seen_intros( $user_id );
	315	+ openstation_clear_seen_intros( $user_id );
255	316	return rest_ensure_response(
256		- array( 'seenIntros' => desktop_mode_get_seen_intros( $user_id ) )
	317	+ array( 'seenIntros' => openstation_get_seen_intros( $user_id ) )
257	318	);
258	319	}