desktop-mode / includes / helpers.php

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

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