class-acf-options-page.php — Secure Custom Fields 6.9.1

secure-custom-fields / includes / class-acf-options-page.php

secure-custom-fields / includes Last commit date

class-acf-options-page.php

559 lines

1	<?php
2	/**
3	* Options Page Class
4	*
5	* Handles the creation and management of global options pages.
6	*
7	* @package wordpress/secure-custom-fields
8	*/
9
10	// phpcs:disable PEAR.NamingConventions.ValidClassName
11	// phpcs:disable Universal.Files.SeparateFunctionsFromOO.Mixed -- @todo
12	if ( ! defined( 'ABSPATH' ) ) {
13	exit; // Exit if accessed directly
14	}
15
16	if ( ! class_exists( 'acf_options_page' ) ) :
17
18	/**
19	* Manages the creation and configuration of WordPress admin options pages.
20	*/
21	class acf_options_page {
22
23	/**
24	* Storage for registered options pages.
25	*
26	* @var array $pages Contains an array of options page settings.
27	*/
28	public $pages = array();
29
30
31	/**
32	* Empty constructor.
33	*
34	* @return void
35	*/
36	public function __construct() {
37
38	/* do nothing */
39	}
40
41	/**
42	* Validates an Options Page settings array.
43	*
44	* @date 28/2/17
45	* @since ACF 5.5.8
46	*
47	* @param array\|string $page The Options Page settings array or name.
48	* @return array
49	*/
50	public function validate_page( $page ) {
51
52	// Allow empty arg to generate the default Options Page.
53	if ( empty( $page ) ) {
54	$page_title = __( 'Options', 'secure-custom-fields' );
55	$page = array(
56	'page_title' => $page_title,
57	'menu_title' => $page_title,
58	'menu_slug' => 'acf-options',
59	);
60
61	// Allow string to define Options Page name.
62	} elseif ( is_string( $page ) ) {
63	$page_title = $page;
64	$page = array(
65	'page_title' => $page_title,
66	'menu_title' => $page_title,
67	);
68	}
69
70	// Apply defaults.
71	$page = wp_parse_args(
72	$page,
73	array(
74	'page_title' => '',
75	'menu_title' => '',
76	'menu_slug' => '',
77	'capability' => 'edit_posts',
78	'parent_slug' => '',
79	'position' => null,
80	'icon_url' => false,
81	'redirect' => true,
82	'post_id' => 'options',
83	'autoload' => false,
84	'update_button' => __( 'Update', 'secure-custom-fields' ),
85	'updated_message' => __( 'Options Updated', 'secure-custom-fields' ),
86	)
87	);
88
89	// Allow compatibility for changed settings.
90	$migrate = array(
91	'title' => 'page_title',
92	'menu' => 'menu_title',
93	'slug' => 'menu_slug',
94	'parent' => 'parent_slug',
95	);
96	foreach ( $migrate as $old => $new ) {
97	if ( ! empty( $page[ $old ] ) ) {
98	$page[ $new ] = $page[ $old ];
99	}
100	}
101
102	// If no menu_title is set, use the page_title value.
103	if ( empty( $page['menu_title'] ) ) {
104	$page['menu_title'] = $page['page_title'];
105	}
106
107	// If no menu_slug is set, generate one using the menu_title value.
108	if ( empty( $page['menu_slug'] ) ) {
109	$page['menu_slug'] = 'acf-options-' . sanitize_title( $page['menu_title'] );
110	}
111
112	// Standardize on position being either null or int.
113	$page['position'] = is_numeric( $page['position'] ) ? (int) $page['position'] : null;
114
115	/**
116	* Filters the $page array after it has been validated.
117	*
118	* @since ACF 5.5.8
119	* @param array $page The Options Page settings array.
120	*/
121	return apply_filters( 'acf/validate_options_page', $page );
122	}
123
124
125	/**
126	* This function will store an options page settings
127	*
128	* @type function
129	* @date 9/6/17
130	* @since ACF 5.6.0
131	*
132	* @param array $page The options page settings array.
133	* @return array\|bool The page settings array or false if already exists.
134	*/
135	public function add_page( $page ) {
136
137	// validate
138	$page = $this->validate_page( $page );
139	$slug = $page['menu_slug'];
140
141	// bail early if already exists
142	if ( isset( $this->pages[ $slug ] ) ) {
143	return false;
144	}
145
146	// append
147	$this->pages[ $slug ] = $page;
148
149	// return
150	return $page;
151	}
152
153
154	/**
155	* Adds a sub page to an existing options page.
156	*
157	* @type function
158	* @date 9/6/17
159	* @since ACF 5.6.0
160	*
161	* @param array $page The options sub page settings array.
162	* @return array\|bool The page settings array or false if parent doesn't exist.
163	*/
164	public function add_sub_page( $page ) {
165
166	// validate
167	$page = $this->validate_page( $page );
168
169	// default parent
170	if ( ! $page['parent_slug'] ) {
171	$page['parent_slug'] = 'acf-options';
172	}
173
174	// create default parent if not yet exists
175	if ( 'acf-options' === $page['parent_slug'] && ! $this->get_page( 'acf-options' ) ) {
176	$this->add_page( '' );
177	}
178
179	// return
180	return $this->add_page( $page );
181	}
182
183
184	/**
185	* Updates an existing options page settings.
186	*
187	* @type function
188	* @date 9/6/17
189	* @since ACF 5.6.0
190	*
191	* @param string $slug The menu slug of the options page.
192	* @param array $data Array of options page settings to update.
193	* @return array\|bool The updated page settings array or false if page not found.
194	*/
195	public function update_page( $slug = '', $data = array() ) {
196
197	// vars
198	$page = $this->get_page( $slug );
199
200	// bail early if no page
201	if ( ! $page ) {
202	return false;
203	}
204
205	// loop
206	$page = array_merge( $page, $data );
207
208	// set
209	$this->pages[ $slug ] = $page;
210
211	// return
212	return $page;
213	}
214
215
216	/**
217	* Returns an options page settings array by slug.
218	*
219	* @type function
220	* @date 6/07/2016
221	* @since ACF 5.4.0
222	*
223	* @param string $slug The menu slug of the options page.
224	* @return array\|null The options page settings array or null if not found.
225	*/
226	public function get_page( $slug ) {
227
228	return isset( $this->pages[ $slug ] ) ? $this->pages[ $slug ] : null;
229	}
230
231
232	/**
233	* Returns all registered options page settings.
234	*
235	* @type function
236	* @date 6/07/2016
237	* @since ACF 5.4.0
238	*
239	* @return array Array of all registered options pages.
240	*/
241	public function get_pages() {
242
243	return $this->pages;
244	}
245	}
246
247
248	/*
249	* acf_options_page
250	*
251	* This function will return the options page instance
252	*
253	* @type function
254	* @date 9/6/17
255	* @since ACF 5.6.0
256	*
257	* @param n/a
258	* @return (object)
259	*/
260
261	/**
262	* Returns the options page instance.
263	*
264	* @type function
265	* @date 9/6/17
266	* @since ACF 5.6.0
267	*
268	* @return object The options page instance.
269	*/
270	function acf_options_page() {
271
272	global $acf_options_page;
273
274	if ( ! isset( $acf_options_page ) ) {
275	$acf_options_page = new acf_options_page();
276	}
277
278	return $acf_options_page;
279	}
280
281
282	// remove Options Page add-on conflict
283	unset( $GLOBALS['acf_options_page'] );
284
285
286	// initialize
287	acf_options_page();
288	endif; // class_exists check
289
290
291	if ( ! function_exists( 'acf_add_options_page' ) ) :
292	/**
293	* Alias of acf_options_page()->add_page()
294	*
295	* @type function
296	* @date 24/02/2014
297	* @since ACF 5.0.0
298	*
299	* @param mixed $page The options page settings.
300	* @return array The page settings array.
301	*/
302	function acf_add_options_page( $page = '' ) {
303	return acf_options_page()->add_page( $page );
304	}
305
306	endif;
307
308
309	if ( ! function_exists( 'acf_add_options_sub_page' ) ) :
310
311	/**
312	* Adds a sub page to an existing options page.
313	*
314	* @type function
315	* @date 24/02/2014
316	* @since ACF 5.0.0
317	*
318	* @param mixed $page The options sub page settings.
319	* @return array The page settings array.
320	*/
321	function acf_add_options_sub_page( $page = '' ) {
322
323	return acf_options_page()->add_sub_page( $page );
324	}
325
326	endif;
327
328
329	if ( ! function_exists( 'acf_update_options_page' ) ) :
330
331	/**
332	* Alias of acf_options_page()->update_page()
333	*
334	* @type function
335	* @date 24/02/2014
336	* @since ACF 5.0.0
337	*
338	* @param string $slug The menu slug of the options page.
339	* @param array $data Array of options page settings to update.
340	* @return array The updated page settings array.
341	*/
342	function acf_update_options_page( $slug = '', $data = array() ) {
343
344	return acf_options_page()->update_page( $slug, $data );
345	}
346
347	endif;
348
349	if ( ! function_exists( 'acf_get_options_page' ) ) :
350	/**
351	* Returns an options page settings array.
352	*
353	* @type function
354	* @date 24/02/2014
355	* @since ACF 5.0.0
356	*
357	* @param string $slug The menu slug of the options page.
358	* @return array\|bool The options page settings array or false if not found.
359	*/
360	function acf_get_options_page( $slug ) {
361
362	// vars
363	$page = acf_options_page()->get_page( $slug );
364
365	// bail early if no page
366	if ( ! $page ) {
367	return false;
368	}
369
370	// filter
371	$page = apply_filters( 'acf/get_options_page', $page, $slug );
372
373	// return
374	return $page;
375	}
376
377	endif;
378
379	if ( ! function_exists( 'acf_get_options_pages' ) ) :
380	/**
381	* This function will return all options page settings
382	*
383	* @type function
384	* @date 24/02/2014
385	* @since ACF 5.0.0
386	*
387	* @return array\|bool The options page settings array or false if no pages are registered.
388	*/
389	function acf_get_options_pages() {
390
391	// global
392	global $_wp_last_utility_menu;
393
394	// vars
395	$pages = acf_options_page()->get_pages();
396
397	// bail early if no pages
398	if ( empty( $pages ) ) {
399	return false;
400	}
401
402	// apply filter to each page
403	foreach ( $pages as $slug => &$page ) {
404	$page = acf_get_options_page( $slug );
405	}
406
407	// calculate parent => child redirects
408	foreach ( $pages as $slug => &$page ) {
409
410	// bail early if is child
411	if ( $page['parent_slug'] ) {
412	continue;
413	}
414
415	// add missing position
416	if ( ! $page['position'] ) {
417	++$_wp_last_utility_menu;
418	$page['position'] = $_wp_last_utility_menu;
419	}
420
421	// bail early if no redirect
422	if ( ! $page['redirect'] ) {
423	continue;
424	}
425
426	// vars
427	$parent = $page['menu_slug'];
428	$child = '';
429
430	// update children
431	foreach ( $pages as &$sub_page ) {
432
433	// bail early if not child of this parent
434	if ( $sub_page['parent_slug'] !== $parent ) {
435	continue;
436	}
437
438	// set child (only once)
439	if ( ! $child ) {
440	$child = $sub_page['menu_slug'];
441	}
442
443	// update parent_slug to the first child
444	$sub_page['parent_slug'] = $child;
445	}
446
447	// finally update parent menu_slug
448	if ( $child ) {
449	$page['_menu_slug'] = $page['menu_slug'];
450	$page['menu_slug'] = $child;
451	}
452	}
453
454	// filter
455	$pages = apply_filters( 'acf/get_options_pages', $pages );
456
457	// return
458	return $pages;
459	}
460
461	endif;
462
463
464
465	if ( ! function_exists( 'acf_set_options_page_title' ) ) :
466
467	/**
468	* This function is used to customize the options page admin menu title
469	*
470	* @type function
471	* @date 13/07/13
472	* @since ACF 4.0.0
473	*
474	* @param string $title The title of the options page.
475	* @return void
476	*/
477	function acf_set_options_page_title( $title = 'Options' ) {
478
479	acf_update_options_page(
480	'acf-options',
481	array(
482	'page_title' => $title,
483	'menu_title' => $title,
484	)
485	);
486	}
487
488	endif;
489
490
491
492	if ( ! function_exists( 'acf_set_options_page_menu' ) ) :
493	/**
494	* This function is used to customize the options page admin menu name
495	*
496	* @type function
497	* @date 13/07/13
498	* @since ACF 4.0.0
499	*
500	* @param string $title The title of the options page.
501	* @return void
502	*/
503	function acf_set_options_page_menu( $title = 'Options' ) {
504
505	acf_update_options_page(
506	'acf-options',
507	array(
508	'menu_title' => $title,
509	)
510	);
511	}
512
513	endif;
514
515
516
517	if ( ! function_exists( 'acf_set_options_page_capability' ) ) :
518	/**
519	* This function is used to customize the options page capability. Defaults to 'edit_posts'
520	*
521	* @type function
522	* @date 13/07/13
523	* @since ACF 4.0.0
524	*
525	* @param string $capability The capability of the options page.
526	* @return void
527	*/
528	function acf_set_options_page_capability( $capability = 'edit_posts' ) {
529
530	acf_update_options_page(
531	'acf-options',
532	array(
533	'capability' => $capability,
534	)
535	);
536	}
537
538	endif;
539
540
541
542	if ( ! function_exists( 'register_options_page' ) ) :
543	/**
544	* This is an old function which is now referencing the new 'acf_add_options_sub_page' function
545	*
546	* @type function
547	* @since ACF 3.0.0
548	* @date 29/01/13
549	*
550	* @param string $page The options sub page settings array.
551	* @return void
552	*/
553	function register_options_page( $page = '' ) {
554
555	acf_add_options_sub_page( $page );
556	}
557
558	endif;
559