jetpack / jetpack_vendor / automattic / jetpack-premium-analytics / src / dashboard-sections.php

dashboard-sections.php in Jetpack – WP Security, Backup, Speed, & Growth 16.3-a.7, at jetpack_vendor/automattic/jetpack-premium-analytics/src/dashboard-sections.php

346 lines 11.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Dashboard Sections API: the registry helpers, the section script data, and the REST routes.
4	*
5	* The package's own sections register through this API from default-dashboard-sections.php,
6	* the same way a plugin extending the dashboard does.
7	*
8	* @package automattic/jetpack-premium-analytics
9	*/
10
11	namespace Automattic\Jetpack\PremiumAnalytics;
12
13	require_once __DIR__ . '/dashboard-layout.php';
14	require_once __DIR__ . '/dashboard-grammar.php';
15	require_once __DIR__ . '/rest-namespace.php';
16	require_once __DIR__ . '/class-dashboard-section.php';
17	require_once __DIR__ . '/class-dashboard-section-registry.php';
18
19	// Guarded on a symbol the file declares, so a second copy of the package can't redeclare it.
20	if ( ! function_exists( __NAMESPACE__ . '\\register_dashboard_feature_flags' ) ) {
21	require_once __DIR__ . '/dashboard-policy.php';
22	}
23
24	/**
25	* Registers a dashboard section.
26	*
27	* @param string $dashboard_name Dashboard identifier.
28	* @param string $id Section identifier.
29	* @param array $args Optional. Section arguments.
30	* @return Dashboard_Section\|false The registered section on success, or false on failure.
31	*/
32	function register_dashboard_section( $dashboard_name, $id, $args = array() ) {
33	return Dashboard_Section_Registry::get_instance()->register( $dashboard_name, $id, $args );
34	}
35
36	/**
37	* Retrieves a registered dashboard section.
38	*
39	* @param string $dashboard_name Dashboard identifier.
40	* @param string $id Section identifier.
41	* @return Dashboard_Section\|null The registered section, or null when absent.
42	*/
43	function get_registered_dashboard_section( $dashboard_name, $id ) {
44	return Dashboard_Section_Registry::get_instance()->get_registered( $dashboard_name, $id );
45	}
46
47	/**
48	* Retrieves available dashboard sections.
49	*
50	* @param string $dashboard_name Dashboard identifier.
51	* @return Dashboard_Section[] Ordered list of available sections.
52	*/
53	function get_available_dashboard_sections( $dashboard_name ) {
54	return Dashboard_Section_Registry::get_instance()->get_available_sections( $dashboard_name );
55	}
56
57	/**
58	* Slugs of the tabs the dashboard exposes, for the client's report routes.
59	*
60	* Reads the same sections the tab list does, so a report cannot outlive the tab it sits
61	* behind. Null, never `array()`, while nothing is registered: an empty array means no
62	* tab is available.
63	*
64	* @since 0.6.0
65	*
66	* @return string[]\|null
67	*/
68	function get_available_dashboard_section_slugs() {
69	$registry = Dashboard_Section_Registry::get_instance();
70
71	if ( empty( $registry->get_all_registered( DASHBOARD_NAME ) ) ) {
72	return null;
73	}
74
75	return array_map(
76	static function ( Dashboard_Section $section ) {
77	return $section->slug;
78	},
79	$registry->get_available_sections( DASHBOARD_NAME )
80	);
81	}
82
83	/**
84	* Configures the section script data.
85	*
86	* @since 0.6.0
87	*
88	* @return void
89	*/
90	function configure_dashboard_sections_script_data() {
91	add_filter( 'jetpack_admin_js_script_data', __NAMESPACE__ . '\\inject_dashboard_sections_script_data', 20 );
92	}
93
94	/**
95	* Kept for older copies of the package, whose Dashboard_Section::is_available() calls it on every
96	* availability check. Every section is in scope now, so the section's own rule decides.
97	*
98	* @since 0.6.0
99	* @deprecated 0.10.0 The preview scope is gone.
100	*
101	* @param string $dashboard_name Dashboard identifier.
102	* @param string $slug URL-facing section slug.
103	* @return bool Always true.
104	*/
105	function is_dashboard_section_in_preview_scope( $dashboard_name, $slug ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable -- Kept for the signature older copies call.
106	return true;
107	}
108
109	/**
110	* Kept for older copies of the package: they guard their include of this file on another
111	* symbol and call this, so a newer copy loading first must still define it.
112	*
113	* @since 0.6.0
114	* @deprecated 0.10.0 Use configure_dashboard_sections_script_data().
115	*
116	* @return void
117	*/
118	function configure_dashboard_preview_scope() {
119	configure_dashboard_sections_script_data();
120	}
121
122	/**
123	* Injects the available section slugs into JetpackScriptData.
124	*
125	* The same list travels over REST for the tab bar, but a report route reads no REST before
126	* choosing its redirect, so it reads the slugs from boot data instead.
127	*
128	* @since 0.6.0
129	*
130	* @param array $data The script data passed by the assets package.
131	* @return array
132	*/
133	function inject_dashboard_sections_script_data( array $data ): array {
134	$sections = get_available_dashboard_section_slugs();
135
136	if ( null === $sections ) {
137	return $data;
138	}
139
140	if ( ! isset( $data['premium_analytics'] ) \|\| ! is_array( $data['premium_analytics'] ) ) {
141	$data['premium_analytics'] = array();
142	}
143
144	$data['premium_analytics']['sections'] = $sections;
145
146	return $data;
147	}
148
149	/**
150	* Whether the current user can access dashboard section routes.
151	*
152	* @return bool
153	*/
154	function check_dashboard_sections_permission() {
155	return Capabilities::current_user_can_view_analytics();
156	}
157
158	/**
159	* Resolves a route section, including availability checks.
160	*
161	* @param string $dashboard_name Dashboard identifier.
162	* @param string $section_id Section identifier.
163	* @return Dashboard_Section\|\WP_Error Registered available section, or error.
164	*/
165	function get_available_dashboard_section_for_route( $dashboard_name, $section_id ) {
166	$section = get_registered_dashboard_section( $dashboard_name, $section_id );
167
168	if ( ! $section ) {
169	return new \WP_Error(
170	'dashboard_section_not_found',
171	__( 'Dashboard section not found.', 'jetpack-premium-analytics-pkg' ),
172	array( 'status' => 404 )
173	);
174	}
175
176	if ( ! $section->is_available() ) {
177	return new \WP_Error(
178	'dashboard_section_unavailable',
179	__( 'Dashboard section is not available.', 'jetpack-premium-analytics-pkg' ),
180	array( 'status' => 404 )
181	);
182	}
183
184	return $section;
185	}
186
187	/**
188	* REST schema for one dashboard section, as returned by the sections route.
189	*
190	* Mirrored by the frontend's `sections.ts` and reused by WPCOM for Simple sites (see AGENTS.md).
191	*
192	* @since 0.2.0
193	*
194	* @return array The JSON schema for a dashboard section.
195	*/
196	function get_dashboard_section_schema() {
197	return array(
198	'$schema' => 'http://json-schema.org/draft-04/schema#',
199	'title' => 'jetpack-premium-analytics-dashboard-section',
200	'type' => 'object',
201	'properties' => array(
202	'id' => array(
203	'description' => __( 'Namespaced section identifier.', 'jetpack-premium-analytics-pkg' ),
204	'type' => 'string',
205	'readonly' => true,
206	),
207	'slug' => array(
208	'description' => __( 'URL-facing section slug, derived from the identifier.', 'jetpack-premium-analytics-pkg' ),
209	'type' => 'string',
210	'readonly' => true,
211	),
212	'label' => array(
213	'description' => __( 'Translated display label, naming the section tab.', 'jetpack-premium-analytics-pkg' ),
214	'type' => 'string',
215	'readonly' => true,
216	),
217	'title' => array(
218	'description' => __( 'Translated section heading, distinct from the tab label. Null falls back to the label.', 'jetpack-premium-analytics-pkg' ),
219	'type' => array( 'string', 'null' ),
220	'readonly' => true,
221	),
222	'order' => array(
223	'description' => __( 'Sort order, ascending.', 'jetpack-premium-analytics-pkg' ),
224	'type' => 'integer',
225	'readonly' => true,
226	),
227	'date_filter' => array(
228	'description' => __( 'Which shape the section date filter takes: the rolling date range, or all time plus single years.', 'jetpack-premium-analytics-pkg' ),
229	'type' => 'string',
230	'enum' => Dashboard_Section::DATE_FILTERS,
231	'default' => Dashboard_Section::DATE_FILTER_RANGE,
232	'readonly' => true,
233	),
234	'date_filter_options' => array(
235	'description' => __( 'What the section date filter supports, and where it renders.', 'jetpack-premium-analytics-pkg' ),
236	'type' => 'object',
237	'properties' => array(
238	'with_date_comparison' => array(
239	'description' => __( 'Whether the section supports period-over-period comparison at all. When false, no widget in the section receives comparison parameters.', 'jetpack-premium-analytics-pkg' ),
240	'type' => 'boolean',
241	'default' => true,
242	),
243	'with_header_date_control' => array(
244	'description' => __( 'Whether the section header renders the date control. When false, the section widgets host their own.', 'jetpack-premium-analytics-pkg' ),
245	'type' => 'boolean',
246	'default' => true,
247	),
248	),
249	'readonly' => true,
250	),
251	'requires_sync' => array(
252	'description' => __( 'Whether the section\'s numbers stay incomplete until the analytics initial full sync has finished.', 'jetpack-premium-analytics-pkg' ),
253	'type' => 'boolean',
254	'default' => false,
255	'readonly' => true,
256	),
257	'default_layout' => array(
258	'description' => __( 'Bundled default widget layout.', 'jetpack-premium-analytics-pkg' ),
259	'type' => 'array',
260	'items' => array( 'type' => 'object' ),
261	'readonly' => true,
262	),
263	),
264	);
265	}
266
267	/**
268	* REST callback returning available dashboard sections.
269	*
270	* @param \WP_REST_Request $request REST request carrying the dashboard name.
271	* @return \WP_REST_Response
272	*/
273	function get_dashboard_sections_response( $request ) {
274	$sections = array_map(
275	static function ( Dashboard_Section $section ) {
276	return $section->to_array();
277	},
278	get_available_dashboard_sections( $request['name'] )
279	);
280
281	return rest_ensure_response( $sections );
282	}
283
284	/**
285	* REST callback returning a section's default layout.
286	*
287	* @param \WP_REST_Request $request REST request carrying dashboard and section identifiers.
288	* @return \WP_REST_Response\|\WP_Error
289	*/
290	function get_dashboard_section_default_layout_response( $request ) {
291	$section = get_available_dashboard_section_for_route( $request['name'], $request['section'] );
292
293	if ( is_wp_error( $section ) ) {
294	return $section;
295	}
296
297	return rest_ensure_response( $section->get_default_layout() );
298	}
299
300	/**
301	* Registers dashboard section REST routes.
302	*
303	* @return void
304	*/
305	function register_dashboard_sections_rest_routes() {
306	register_rest_route(
307	DASHBOARD_REST_NAMESPACE,
308	'/dashboards/(?P<name>' . get_dashboard_name_pattern() . ')/sections',
309	array(
310	array(
311	// @phan-suppress-next-line PhanPluginMixedKeyNoKey -- register_rest_route()'s own signature mixes a numerically keyed endpoint list with a route-level `schema` key.
312	'methods' => \WP_REST_Server::READABLE,
313	'callback' => __NAMESPACE__ . '\\get_dashboard_sections_response',
314	'permission_callback' => __NAMESPACE__ . '\\check_dashboard_sections_permission',
315	'args' => array(
316	'name' => array(
317	'description' => __( 'Dashboard identifier as produced by the build pipeline.', 'jetpack-premium-analytics-pkg' ),
318	'type' => 'string',
319	),
320	),
321	),
322	'schema' => __NAMESPACE__ . '\\get_dashboard_section_schema',
323	)
324	);
325
326	register_rest_route(
327	DASHBOARD_REST_NAMESPACE,
328	'/dashboards/(?P<name>' . get_dashboard_name_pattern() . ')/sections/(?P<section>' . get_dashboard_section_id_pattern() . ')/default-layout',
329	array(
330	'methods' => \WP_REST_Server::READABLE,
331	'callback' => __NAMESPACE__ . '\\get_dashboard_section_default_layout_response',
332	'permission_callback' => __NAMESPACE__ . '\\check_dashboard_sections_permission',
333	'args' => array(
334	'name' => array(
335	'description' => __( 'Dashboard identifier as produced by the build pipeline.', 'jetpack-premium-analytics-pkg' ),
336	'type' => 'string',
337	),
338	'section' => array(
339	'description' => __( 'Dashboard section identifier.', 'jetpack-premium-analytics-pkg' ),
340	'type' => 'string',
341	),
342	),
343	)
344	);
345	}
346