wpgetapi / lib / cmb2 / includes / helper-functions.php

helper-functions.php in WPGet API – Connect to any external REST API 1.4.0, at lib/cmb2/includes/helper-functions.php

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