desktop-mode / includes / helpers.php

helpers.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 0.9.6, at includes/helpers.php

199 lines 6.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Desktop Mode helper functions.
4	*
5	* @package WPDesktopMode
6	*/
7
8	defined( 'ABSPATH' ) \|\| exit;
9
10	/**
11	* Checks whether a user has desktop mode enabled.
12	*
13	* Two gates, both must pass:
14	*
15	* 1. The user's `desktop_mode_mode` user-meta is `'1'` (the per-user
16	* opt-in toggle the admin-bar button writes via the AJAX endpoint).
17	* 2. The `desktop_mode_mode_enabled` filter returns truthy for that user.
18	*
19	* Centralising the filter check here means render-time gates (chromeless
20	* detection, payload generation, REST permission callbacks) can rely on
21	* a single helper instead of every call site re-running the filter.
22	* A user whose meta is `'1'` but whose filter denies them is treated as
23	* not-enabled everywhere, which is the documented contract of the
24	* filter — see docs/examples/gate-by-role.md.
25	*
26	* @since 0.1.0
27	*
28	* @param int $user_id Optional. User ID to check. Defaults to the
29	* current user.
30	* @return bool True if the user has desktop mode active.
31	*/
32	function desktop_mode_is_enabled( $user_id = 0 ) {
33	$user_id = (int) $user_id;
34	if ( $user_id <= 0 ) {
35	if ( ! is_user_logged_in() ) {
36	return false;
37	}
38	$user_id = get_current_user_id();
39	}
40
41	if ( '1' !== (string) get_user_meta( $user_id, 'desktop_mode_mode', true ) ) {
42	return false;
43	}
44
45	/**
46	* Filters whether desktop mode is available for this user.
47	*
48	* See `docs/hooks-reference.md` (`desktop_mode_mode_enabled`) for the
49	* full contract. Returning `false` here makes the helper return
50	* `false` for the user even when their meta is set, which propagates
51	* to every render-time gate that consults the helper.
52	*
53	* @since 0.1.0
54	*
55	* @param bool $enabled Whether desktop mode is enabled. Default true.
56	* @param int $user_id The user ID being checked.
57	*/
58	return (bool) apply_filters( 'desktop_mode_mode_enabled', true, $user_id );
59	}
60
61	/**
62	* Shared REST permission gate for Desktop Mode's per-user endpoints.
63	*
64	* Routes that only ever read or write the current user's own Desktop
65	* Mode state (OS settings, session, default-window, seen-intros, PWA
66	* state, presence) must not be reachable by accounts that haven't
67	* actually entered Desktop Mode.
68	*
69	* `current_user_can( 'read' )` alone is too loose: every authenticated
70	* role — Subscriber included — carries `read`, so the old gate let any
71	* logged-in user touch these routes without ever enabling Desktop Mode.
72	* We gate on {@see desktop_mode_is_enabled()} instead (the same opt-in +
73	* `desktop_mode_mode_enabled` filter the shell itself uses) and return
74	* the conventional 401/403 split so REST clients can tell "log in" from
75	* "not allowed".
76	*
77	* This is the canonical gate; `desktop_mode_presence_rest_permission()`
78	* pioneered the shape and now delegates here.
79	*
80	* @since 0.8.10
81	*
82	* @return true\|WP_Error True when allowed; a `rest_forbidden` WP_Error
83	* (401 when logged out, 403 when desktop mode is
84	* not enabled for the account) otherwise.
85	*/
86	function desktop_mode_rest_require_enabled() {
87	if ( ! is_user_logged_in() ) {
88	return new WP_Error(
89	'rest_forbidden',
90	__( 'Authentication required.', 'desktop-mode' ),
91	array( 'status' => 401 )
92	);
93	}
94
95	if ( ! desktop_mode_is_enabled() ) {
96	return new WP_Error(
97	'rest_forbidden',
98	__( 'Desktop mode is not enabled for your account.', 'desktop-mode' ),
99	array( 'status' => 403 )
100	);
101	}
102
103	return true;
104	}
105
106	// Chromeless / classic admin-bar suppression and the `wp_redirect`
107	// flag-preservation filter pair were moved to
108	// `includes/core/routing.php` in 0.8.1. The functions and the
109	// add_filter / add_action hookings live there now; this file
110	// remains the home of `desktop_mode_is_enabled()` (called from the
111	// routing helpers at hook-fire time, after every include has
112	// loaded), which is why `desktop-mode.php` can safely require
113	// routing.php BEFORE helpers.php.
114
115	/**
116	* `desktop_mode_is_chromeless_request()` and `desktop_mode_is_classic_request()`
117	* were moved to `includes/core/routing.php` in 0.8.1 — see that
118	* file for the canonical definitions. The function names didn't
119	* change; PHP looks them up by name at call time, so every
120	* existing caller (helpers, render, hooks) keeps working.
121	*/
122
123	/**
124	* Returns the default wallpaper id used when a user has no saved
125	* selection (or their saved selection was unregistered by a plugin
126	* deactivation).
127	*
128	* Exposed as a filter so themes/plugins can set a site-wide default
129	* without forking the TS build.
130	*
131	* ```php
132	* add_filter( 'desktop_mode_default_wallpaper', function () {
133	* return 'my-plugin/brand';
134	* } );
135	* ```
136	*
137	* The returned string is passed through `sanitize_key()` so a filter
138	* that returns an invalid slug degrades to the empty string (and the
139	* shell falls back to its hard-coded `'dark'` preset).
140	*
141	* @since 0.5.0
142	*
143	* @return string Wallpaper id. Empty string if the filter returns
144	* an invalid value.
145	*/
146	function desktop_mode_get_default_wallpaper() {
147	/**
148	* Filters the wallpaper id loaded on first boot / new user.
149	*
150	* @since 0.5.0
151	*
152	* @param string $id Default wallpaper slug.
153	*/
154	$id = apply_filters( 'desktop_mode_default_wallpaper', 'dark' );
155	if ( ! is_string( $id ) ) {
156	return '';
157	}
158	return sanitize_key( $id );
159	}
160
161	/**
162	* Build a `WP_Error` for a desktop-mode registration failure.
163	*
164	* Centralises the error-code vocabulary used by every
165	* `desktop_mode_register_*()` function so plugin authors see a
166	* consistent contract. The canonical error-code list lives in
167	* `docs/hooks-reference.md`.
168	*
169	* @since 0.5.0
170	*
171	* @param string $code Short error slug (e.g. `desktop_mode_missing_title`).
172	* @param string $message Human-readable message. Should be translated.
173	* @param array $data Optional extra context attached to the error.
174	* @return WP_Error
175	*/
176	function desktop_mode_registration_error( $code, $message, $data = array() ) {
177	return new WP_Error(
178	(string) $code,
179	(string) $message,
180	is_array( $data ) ? $data : array()
181	);
182	}
183
184	// `desktop_mode_url_is_same_admin()`,
185	// `desktop_mode_resolve_admin_target()` and
186	// `desktop_mode_admin_target_allowlist()` were moved to
187	// `includes/core/routing.php` in 0.8.1 — see that file for the
188	// canonical definitions. Function names didn't change; PHP's
189	// runtime resolution finds them across the module split.
190
191
192	// Dock building, menu / native-windows payload assembly and the
193	// script/style handle resolvers were moved to
194	// `includes/core/payload.php` in 0.8.1. Function names didn't
195	// change; existing callers find them via PHP's runtime function
196	// resolution. desktop-mode.php loads payload.php right after
197	// helpers.php so the foundational helpers (desktop_mode_is_enabled
198	// etc.) are present when payload functions are invoked.
199