gamipress / libraries / cmb2 / includes / helper-functions.php

helper-functions.php in GamiPress – Gamification plugin to reward points, badges & ranks in WordPress, now with AI 8.0.3, at libraries/cmb2/includes/helper-functions.php

430 lines 13.2 KB

Raw Download Zip

1	<?php
2	/**
3	* CMB2 Helper Functions
4	*
5	* @category WordPress_Plugin
6	* @package CMB2
7	* @author CMB2 team
8	* @license GPL-2.0+
9	* @link https://cmb2.io
10	*/
11
12	// Exit if accessed directly
13	if( !defined( 'ABSPATH' ) ) exit;
14
15	/**
16	* Helper function to provide directory path to CMB2
17	*
18	* @since 2.0.0
19	* @param string $path Path to append.
20	* @return string Directory with optional path appended
21	*/
22	function cmb2_dir( $path = '' ) {
23	return CMB2_DIR . $path;
24	}
25
26	/**
27	* Autoloads files with CMB2 classes when needed
28	*
29	* @since 1.0.0
30	* @param string $class_name Name of the class being requested.
31	*/
32	function cmb2_autoload_classes( $class_name ) {
33	if ( 0 !== strpos( $class_name, 'CMB2' ) ) {
34	return;
35	}
36
37	$path = 'includes';
38
39	if ( 'CMB2_Type' === $class_name \|\| 0 === strpos( $class_name, 'CMB2_Type_' ) ) {
40	$path .= '/types';
41	}
42
43	if ( 'CMB2_REST' === $class_name \|\| 0 === strpos( $class_name, 'CMB2_REST_' ) ) {
44	$path .= '/rest-api';
45	}
46
47	include_once cmb2_dir( "$path/{$class_name}.php" );
48	}
49
50	/**
51	* Get instance of the CMB2_Utils class
52	*
53	* @since 2.0.0
54	* @return CMB2_Utils object CMB2 utilities class
55	*/
56	function cmb2_utils() {
57	static $cmb2_utils;
58	$cmb2_utils = $cmb2_utils ? $cmb2_utils : new CMB2_Utils();
59	return $cmb2_utils;
60	}
61
62	/**
63	* Get instance of the CMB2_Ajax class
64	*
65	* @since 2.0.0
66	* @return CMB2_Ajax object CMB2 ajax class
67	*/
68	function cmb2_ajax() {
69	return CMB2_Ajax::get_instance();
70	}
71
72	/**
73	* Get instance of the CMB2_Option class for the passed metabox ID
74	*
75	* @since 2.0.0
76	*
77	* @param string $key Option key to fetch.
78	* @return CMB2_Option object Options class for setting/getting options for metabox
79	*/
80	function cmb2_options( $key ) {
81	return CMB2_Options::get( $key );
82	}
83
84	/**
85	* Get a cmb oEmbed. Handles oEmbed getting for non-post objects
86	*
87	* @since 2.0.0
88	* @param array $args Arguments. Accepts:
89	*
90	* 'url' - URL to retrieve the oEmbed from,
91	* 'object_id' - $post_id,
92	* 'object_type' - 'post',
93	* 'oembed_args' - $embed_args, // array containing 'width', etc
94	* 'field_id' - false,
95	* 'cache_key' - false,
96	* 'wp_error' - true/false, // To return a wp_error object if no embed found.
97	*
98	* @return string oEmbed string
99	*/
100	function cmb2_get_oembed( $args = array() ) {
101	$oembed = cmb2_ajax()->get_oembed_no_edit( $args );
102
103	// Send back our embed.
104	if ( $oembed['embed'] && $oembed['embed'] != $oembed['fallback'] ) {
105	return '<div class="cmb2-oembed">' . $oembed['embed'] . '</div>';
106	}
107
108	$error = sprintf(
109	/* translators: 1: results for. 2: link to codex.wordpress.org/Embeds */
110	esc_html__( 'No oEmbed Results Found for %1$s. View more info at %2$s.', 'cmb2' ),
111	$oembed['fallback'],
112	'<a href="https://wordpress.org/support/article/embeds/" target="_blank">codex.wordpress.org/Embeds</a>'
113	);
114
115	if ( isset( $args['wp_error'] ) && $args['wp_error'] ) {
116	return new WP_Error( 'cmb2_get_oembed_result', $error, compact( 'oembed', 'args' ) );
117	}
118
119	// Otherwise, send back error info that no oEmbeds were found.
120	return '<p class="ui-state-error-text">' . $error . '</p>';
121	}
122
123	/**
124	* Outputs the return of cmb2_get_oembed.
125	*
126	* @since 2.2.2
127	* @see cmb2_get_oembed
128	*
129	* @param array $args oEmbed args.
130	*/
131	function cmb2_do_oembed( $args = array() ) {
132	echo cmb2_get_oembed( $args );
133	}
134	add_action( 'cmb2_do_oembed', 'cmb2_do_oembed' );
135
136	/**
137	* A helper function to get an option from a CMB2 options array
138	*
139	* @since 1.0.1
140	* @param string $option_key Option key.
141	* @param string $field_id Option array field key.
142	* @param mixed $default Optional default fallback value.
143	* @return array Options array or specific field
144	*/
145	function cmb2_get_option( $option_key, $field_id = '', $default = false ) {
146	return cmb2_options( $option_key )->get( $field_id, $default );
147	}
148
149	/**
150	* A helper function to update an option in a CMB2 options array
151	*
152	* @since 2.0.0
153	* @param string $option_key Option key.
154	* @param string $field_id Option array field key.
155	* @param mixed $value Value to update data with.
156	* @param boolean $single Whether data should not be an array.
157	* @return boolean Success/Failure
158	*/
159	function cmb2_update_option( $option_key, $field_id, $value, $single = true ) {
160	if ( cmb2_options( $option_key )->update( $field_id, $value, false, $single ) ) {
161	return cmb2_options( $option_key )->set();
162	}
163
164	return false;
165	}
166
167	/**
168	* Get a CMB2 field object.
169	*
170	* @since 1.1.0
171	* @param array $meta_box Metabox ID or Metabox config array.
172	* @param array $field_id Field ID or all field arguments.
173	* @param int\|string $object_id Object ID (string for options-page).
174	* @param string $object_type Type of object being saved. (e.g., post, user, term, comment, or options-page).
175	* Defaults to metabox object type.
176	* @return CMB2_Field\|null CMB2_Field object unless metabox config cannot be found
177	*/
178	function cmb2_get_field( $meta_box, $field_id, $object_id = 0, $object_type = '' ) {
179
180	$object_id = $object_id ? $object_id : get_the_ID();
181	$cmb = $meta_box instanceof CMB2 ? $meta_box : cmb2_get_metabox( $meta_box, $object_id );
182
183	if ( ! $cmb ) {
184	return;
185	}
186
187	$cmb->object_type( $object_type ? $object_type : $cmb->mb_object_type() );
188
189	return $cmb->get_field( $field_id );
190	}
191
192	/**
193	* Get a field's value.
194	*
195	* @since 1.1.0
196	* @param array $meta_box Metabox ID or Metabox config array.
197	* @param array $field_id Field ID or all field arguments.
198	* @param int\|string $object_id Object ID (string for options-page).
199	* @param string $object_type Type of object being saved. (e.g., post, user, term, comment, or options-page).
200	* Defaults to metabox object type.
201	* @return mixed Maybe escaped value
202	*/
203	function cmb2_get_field_value( $meta_box, $field_id, $object_id = 0, $object_type = '' ) {
204	$field = cmb2_get_field( $meta_box, $field_id, $object_id, $object_type );
205	return $field->escaped_value();
206	}
207
208	/**
209	* Because OOP can be scary
210	*
211	* @since 2.0.2
212	* @param array $meta_box_config Metabox Config array.
213	* @return CMB2 object Instantiated CMB2 object
214	*/
215	function new_cmb2_box( array $meta_box_config ) {
216	return cmb2_get_metabox( $meta_box_config );
217	}
218
219	/**
220	* Retrieve a CMB2 instance by the metabox ID
221	*
222	* @since 2.0.0
223	* @param mixed $meta_box Metabox ID or Metabox config array.
224	* @param int\|string $object_id Object ID (string for options-page).
225	* @param string $object_type Type of object being saved.
226	* (e.g., post, user, term, comment, or options-page).
227	* Defaults to metabox object type.
228	* @return CMB2 object
229	*/
230	function cmb2_get_metabox( $meta_box, $object_id = 0, $object_type = '' ) {
231
232	if ( $meta_box instanceof CMB2 ) {
233	return $meta_box;
234	}
235
236	if ( is_string( $meta_box ) ) {
237	$cmb = CMB2_Boxes::get( $meta_box );
238	} else {
239	// See if we already have an instance of this metabox.
240	$cmb = CMB2_Boxes::get( $meta_box['id'] );
241	// If not, we'll initate a new metabox.
242	$cmb = $cmb ? $cmb : new CMB2( $meta_box, $object_id );
243	}
244
245	if ( $cmb && $object_id ) {
246	$cmb->object_id( $object_id );
247	}
248
249	if ( $cmb && $object_type ) {
250	$cmb->object_type( $object_type );
251	}
252
253	return $cmb;
254	}
255
256	/**
257	* Returns array of sanitized field values from a metabox (without saving them)
258	*
259	* @since 2.0.3
260	* @param mixed $meta_box Metabox ID or Metabox config array.
261	* @param array $data_to_sanitize Array of field_id => value data for sanitizing (likely $_POST data).
262	* @return mixed Array of sanitized values or false if no CMB2 object found
263	*/
264	function cmb2_get_metabox_sanitized_values( $meta_box, array $data_to_sanitize ) {
265	$cmb = cmb2_get_metabox( $meta_box );
266	return $cmb ? $cmb->get_sanitized_values( $data_to_sanitize ) : false;
267	}
268
269	/**
270	* Retrieve a metabox form
271	*
272	* @since 2.0.0
273	* @param mixed $meta_box Metabox config array or Metabox ID.
274	* @param int\|string $object_id Object ID (string for options-page).
275	* @param array $args Optional arguments array.
276	* @return string CMB2 html form markup
277	*/
278	function cmb2_get_metabox_form( $meta_box, $object_id = 0, $args = array() ) {
279
280	$object_id = $object_id ? $object_id : get_the_ID();
281	$cmb = cmb2_get_metabox( $meta_box, $object_id );
282
283	ob_start();
284	// Get cmb form.
285	cmb2_print_metabox_form( $cmb, $object_id, $args );
286	$form = ob_get_clean();
287
288	return apply_filters( 'cmb2_get_metabox_form', $form, $object_id, $cmb );
289	}
290
291	/**
292	* Display a metabox form & save it on submission
293	*
294	* @since 1.0.0
295	* @param mixed $meta_box Metabox config array or Metabox ID.
296	* @param int\|string $object_id Object ID (string for options-page).
297	* @param array $args Optional arguments array.
298	*/
299	function cmb2_print_metabox_form( $meta_box, $object_id = 0, $args = array() ) {
300
301	$object_id = $object_id ? $object_id : get_the_ID();
302	$cmb = cmb2_get_metabox( $meta_box, $object_id );
303
304	// if passing a metabox ID, and that ID was not found.
305	if ( ! $cmb ) {
306	return;
307	}
308
309	$args = wp_parse_args( $args, array(
310	'form_format' => '<form class="cmb-form" method="post" id="%1$s" enctype="multipart/form-data" encoding="multipart/form-data"><input type="hidden" name="object_id" value="%2$s">%3$s<input type="submit" name="submit-cmb" value="%4$s" class="button-primary"></form>',
311	'save_button' => esc_html__( 'Save', 'cmb2' ),
312	'object_type' => $cmb->mb_object_type(),
313	'cmb_styles' => $cmb->prop( 'cmb_styles' ),
314	'enqueue_js' => $cmb->prop( 'enqueue_js' ),
315	) );
316
317	// Set object type explicitly (rather than trying to guess from context).
318	$cmb->object_type( $args['object_type'] );
319
320	// Save the metabox if it's been submitted
321	// check permissions
322	// @todo more hardening?
323	if (
324	$cmb->prop( 'save_fields' )
325	// check nonce.
326	&& isset( $_POST['submit-cmb'], $_POST['object_id'], $_POST[ $cmb->nonce() ] )
327	&& wp_verify_nonce( $_POST[ $cmb->nonce() ], $cmb->nonce() )
328	&& $object_id && $_POST['object_id'] == $object_id
329	) {
330	$cmb->save_fields( $object_id, $cmb->object_type(), $_POST );
331	}
332
333	// Enqueue JS/CSS.
334	if ( $args['cmb_styles'] ) {
335	CMB2_Hookup::enqueue_cmb_css();
336	}
337
338	if ( $args['enqueue_js'] ) {
339	CMB2_Hookup::enqueue_cmb_js();
340	}
341
342	$form_format = apply_filters( 'cmb2_get_metabox_form_format', $args['form_format'], $object_id, $cmb );
343
344	$format_parts = explode( '%3$s', $form_format );
345
346	// Show cmb form.
347	printf( $format_parts[0], esc_attr( $cmb->cmb_id ), esc_attr( $object_id ) );
348	$cmb->show_form();
349
350	if ( isset( $format_parts[1] ) && $format_parts[1] ) {
351	printf( str_ireplace( '%4$s', '%1$s', $format_parts[1] ), esc_attr( $args['save_button'] ) );
352	}
353	}
354
355	/**
356	* Display a metabox form (or optionally return it) & save it on submission.
357	*
358	* @since 1.0.0
359	* @param mixed $meta_box Metabox config array or Metabox ID.
360	* @param int\|string $object_id Object ID (string for options-page).
361	* @param array $args Optional arguments array.
362	* @return string
363	*/
364	function cmb2_metabox_form( $meta_box, $object_id = 0, $args = array() ) {
365	if ( ! isset( $args['echo'] ) \|\| $args['echo'] ) {
366	cmb2_print_metabox_form( $meta_box, $object_id, $args );
367	} else {
368	return cmb2_get_metabox_form( $meta_box, $object_id, $args );
369	}
370	}
371
372	if ( ! function_exists( 'date_create_from_format' ) ) {
373
374	/**
375	* Reimplementation of DateTime::createFromFormat for PHP < 5.3. :(
376	* Borrowed from http://stackoverflow.com/questions/5399075/php-datetimecreatefromformat-in-5-2
377	*
378	* @param string $date_format Date format.
379	* @param string $date_value Date value.
380	*
381	* @return DateTime
382	*/
383	function date_create_from_format( $date_format, $date_value ) {
384
385	$schedule_format = str_replace(
386	array( 'M', 'Y', 'm', 'd', 'H', 'i', 'a' ),
387	array( '%b', '%Y', '%m', '%d', '%H', '%M', '%p' ),
388	$date_format
389	);
390
391	/*
392	* %Y, %m and %d correspond to date()'s Y m and d.
393	* %I corresponds to H, %M to i and %p to a
394	*/
395	$parsed_time = date_parse_from_format( $schedule_format, $date_value );
396
397	$ymd = sprintf(
398	/**
399	* This is a format string that takes six total decimal
400	* arguments, then left-pads them with zeros to either
401	* 4 or 2 characters, as needed
402	*/
403	'%04d-%02d-%02d %02d:%02d:%02d',
404	$parsed_time['tm_year'] + 1900, // This will be "111", so we need to add 1900.
405	$parsed_time['tm_mon'] + 1, // This will be the month minus one, so we add one.
406	$parsed_time['tm_mday'],
407	$parsed_time['tm_hour'],
408	$parsed_time['tm_min'],
409	$parsed_time['tm_sec']
410	);
411
412	return new DateTime( $ymd );
413	}
414	}// End if.
415
416	if ( ! function_exists( 'date_timestamp_get' ) ) {
417
418	/**
419	* Returns the Unix timestamp representing the date.
420	* Reimplementation of DateTime::getTimestamp for PHP < 5.3. :(
421	*
422	* @param DateTime $date DateTime instance.
423	*
424	* @return int
425	*/
426	function date_timestamp_get( DateTime $date ) {
427	return $date->format( 'U' );
428	}
429	}// End if.
430