desktop-mode / includes / helpers.php

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

154 lines 5.1 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	// Chromeless / classic admin-bar suppression and the `wp_redirect`
62	// flag-preservation filter pair were moved to
63	// `includes/core/routing.php` in 0.8.1. The functions and the
64	// add_filter / add_action hookings live there now; this file
65	// remains the home of `desktop_mode_is_chromeless_request()` and
66	// `desktop_mode_is_classic_request()` (called from the routing
67	// helpers at hook-fire time), which is why
68	// `desktop-mode.php` requires routing.php BEFORE helpers.php.
69
70	/**
71	* `desktop_mode_is_chromeless_request()` and `desktop_mode_is_classic_request()`
72	* were moved to `includes/core/routing.php` in 0.8.1 — see that
73	* file for the canonical definitions. The function names didn't
74	* change; PHP looks them up by name at call time, so every
75	* existing caller (helpers, render, hooks) keeps working.
76	*/
77
78	/**
79	* Returns the default wallpaper id used when a user has no saved
80	* selection (or their saved selection was unregistered by a plugin
81	* deactivation).
82	*
83	* Exposed as a filter so themes/plugins can set a site-wide default
84	* without forking the TS build.
85	*
86	* ```php
87	* add_filter( 'desktop_mode_default_wallpaper', function () {
88	* return 'my-plugin/brand';
89	* } );
90	* ```
91	*
92	* The returned string is passed through `sanitize_key()` so a filter
93	* that returns an invalid slug degrades to the empty string (and the
94	* shell falls back to its hard-coded `'dark'` preset).
95	*
96	* @since 0.11.0
97	*
98	* @return string Wallpaper id. Empty string if the filter returns
99	* an invalid value.
100	*/
101	function desktop_mode_get_default_wallpaper() {
102	/**
103	* Filters the wallpaper id loaded on first boot / new user.
104	*
105	* @since 0.11.0
106	*
107	* @param string $id Default wallpaper slug.
108	*/
109	$id = apply_filters( 'desktop_mode_default_wallpaper', 'dark' );
110	if ( ! is_string( $id ) ) {
111	return '';
112	}
113	return sanitize_key( $id );
114	}
115
116	/**
117	* Build a `WP_Error` for a desktop-mode registration failure.
118	*
119	* Centralises the error-code vocabulary used by every
120	* `desktop_mode_register_*()` function so plugin authors see a
121	* consistent contract. The canonical error-code list lives in
122	* `docs/hooks-reference.md`.
123	*
124	* @since 0.11.0
125	*
126	* @param string $code Short error slug (e.g. `desktop_mode_missing_title`).
127	* @param string $message Human-readable message. Should be translated.
128	* @param array $data Optional extra context attached to the error.
129	* @return WP_Error
130	*/
131	function desktop_mode_registration_error( $code, $message, $data = array() ) {
132	return new WP_Error(
133	(string) $code,
134	(string) $message,
135	is_array( $data ) ? $data : array()
136	);
137	}
138
139	// `desktop_mode_url_is_same_admin()`,
140	// `desktop_mode_resolve_admin_target()` and
141	// `desktop_mode_admin_target_allowlist()` were moved to
142	// `includes/core/routing.php` in 0.8.1 — see that file for the
143	// canonical definitions. Function names didn't change; PHP's
144	// runtime resolution finds them across the module split.
145
146
147	// Dock building, menu / native-windows payload assembly and the
148	// script/style handle resolvers were moved to
149	// `includes/core/payload.php` in 0.8.1. Function names didn't
150	// change; existing callers find them via PHP's runtime function
151	// resolution. desktop-mode.php loads payload.php right after
152	// helpers.php so the foundational helpers (desktop_mode_is_enabled
153	// etc.) are present when payload functions are invoked.
154