acf-helper-functions.php — Secure Custom Fields 6.9.1

secure-custom-fields / includes / acf-helper-functions.php

secure-custom-fields / includes Last commit date

acf-helper-functions.php

654 lines

1	<?php
2
3	/**
4	* Returns true if the value provided is considered "empty". Allows numbers such as 0.
5	*
6	* @date 6/7/16
7	* @since ACF 5.4.0
8	*
9	* @param mixed $var The value to check.
10	* @return boolean
11	*/
12	function acf_is_empty( $var ) {
13	return ( ! $var && ! is_numeric( $var ) );
14	}
15
16	/**
17	* Returns true if the value provided is considered "not empty". Allows numbers such as 0.
18	*
19	* @date 15/7/19
20	* @since ACF 5.8.1
21	*
22	* @param mixed $var The value to check.
23	* @return boolean
24	*/
25	function acf_not_empty( $var ) {
26	return ( $var \|\| is_numeric( $var ) );
27	}
28
29	/**
30	* Returns a unique numeric based id.
31	*
32	* @date 9/1/19
33	* @since ACF 5.7.10
34	*
35	* @param string $prefix The id prefix. Defaults to 'acf'.
36	* @return string
37	*/
38	function acf_uniqid( $prefix = 'acf' ) {
39
40	// Instantiate global counter.
41	global $acf_uniqid;
42	if ( ! isset( $acf_uniqid ) ) {
43	$acf_uniqid = 1;
44	}
45
46	// Return id.
47	return $prefix . '-' . $acf_uniqid++;
48	}
49
50	/**
51	* Merges together two arrays but with extra functionality to append class names.
52	*
53	* @date 22/1/19
54	* @since ACF 5.7.10
55	*
56	* @param array $array1 An array of attributes.
57	* @param array $array2 An array of attributes.
58	* @return array
59	*/
60	function acf_merge_attributes( $array1, $array2 ) {
61
62	// Merge together attributes.
63	$array3 = array_merge( $array1, $array2 );
64
65	// Append together special attributes.
66	foreach ( array( 'class', 'style' ) as $key ) {
67	if ( isset( $array1[ $key ] ) && isset( $array2[ $key ] ) ) {
68	$array3[ $key ] = trim( $array1[ $key ] ) . ' ' . trim( $array2[ $key ] );
69	}
70	}
71
72	// Return.
73	return $array3;
74	}
75
76	/**
77	* acf_cache_key
78	*
79	* Returns a filtered cache key.
80	*
81	* @date 25/1/19
82	* @since ACF 5.7.11
83	*
84	* @param string $key The cache key.
85	* @return string
86	*/
87	function acf_cache_key( $key = '' ) {
88
89	/**
90	* Filters the cache key.
91	*
92	* @date 25/1/19
93	* @since ACF 5.7.11
94	*
95	* @param string $key The cache key.
96	* @param string $original_key The original cache key.
97	*/
98	return apply_filters( 'acf/get_cache_key', $key, $key );
99	}
100
101	/**
102	* acf_request_args
103	*
104	* Returns an array of $_REQUEST values using the provided defaults.
105	*
106	* @date 28/2/19
107	* @since ACF 5.7.13
108	*
109	* @param array $args An array of args.
110	* @return array
111	*/
112	function acf_request_args( $args = array() ) {
113	foreach ( $args as $k => $v ) {
114	$args[ $k ] = isset( $_REQUEST[ $k ] ) ? acf_sanitize_request_args( $_REQUEST[ $k ] ) : $args[ $k ]; // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Verified elsewhere.
115	}
116	return $args;
117	}
118
119	/**
120	* Returns a single $_REQUEST arg with fallback.
121	*
122	* @date 23/10/20
123	* @since ACF 5.9.2
124	*
125	* @param string $key The property name.
126	* @param mixed $default The default value to fallback to.
127	* @return mixed
128	*/
129	function acf_request_arg( $name = '', $default = null ) {
130	return isset( $_REQUEST[ $name ] ) ? acf_sanitize_request_args( $_REQUEST[ $name ] ) : $default; // phpcs:ignore WordPress.Security.NonceVerification.Recommended
131	}
132
133	// Register store.
134	acf_register_store( 'filters' );
135
136	/**
137	* acf_enable_filter
138	*
139	* Enables a filter with the given name.
140	*
141	* @date 14/7/16
142	* @since ACF 5.4.0
143	*
144	* @param string $name The modifier name.
145	* @return void
146	*/
147	function acf_enable_filter( $name = '' ) {
148	acf_get_store( 'filters' )->set( $name, true );
149	}
150
151	/**
152	* acf_disable_filter
153	*
154	* Disables a filter with the given name.
155	*
156	* @date 14/7/16
157	* @since ACF 5.4.0
158	*
159	* @param string $name The modifier name.
160	* @return void
161	*/
162	function acf_disable_filter( $name = '' ) {
163	acf_get_store( 'filters' )->set( $name, false );
164	}
165
166	/**
167	* acf_is_filter_enabled
168	*
169	* Returns the state of a filter for the given name.
170	*
171	* @date 14/7/16
172	* @since ACF 5.4.0
173	*
174	* @param string $name The modifier name.
175	* @return array
176	*/
177	function acf_is_filter_enabled( $name = '' ) {
178	return acf_get_store( 'filters' )->get( $name );
179	}
180
181	/**
182	* acf_get_filters
183	*
184	* Returns an array of filters in their current state.
185	*
186	* @date 14/7/16
187	* @since ACF 5.4.0
188	*
189	* @return array
190	*/
191	function acf_get_filters() {
192	return acf_get_store( 'filters' )->get();
193	}
194
195	/**
196	* acf_set_filters
197	*
198	* Sets an array of filter states.
199	*
200	* @date 14/7/16
201	* @since ACF 5.4.0
202	*
203	* @param array $filters An Array of modifiers.
204	* @return void
205	*/
206	function acf_set_filters( $filters = array() ) {
207	acf_get_store( 'filters' )->set( $filters );
208	}
209
210	/**
211	* acf_disable_filters
212	*
213	* Disables all filters and returns the previous state.
214	*
215	* @date 14/7/16
216	* @since ACF 5.4.0
217	*
218	* @return array
219	*/
220	function acf_disable_filters() {
221
222	// Get state.
223	$prev_state = acf_get_filters();
224
225	// Set all modifiers as false.
226	acf_set_filters( array_map( '__return_false', $prev_state ) );
227
228	// Return prev state.
229	return $prev_state;
230	}
231
232	/**
233	* acf_enable_filters
234	*
235	* Enables all or an array of specific filters and returns the previous state.
236	*
237	* @date 14/7/16
238	* @since ACF 5.4.0
239	*
240	* @param array $filters An Array of modifiers.
241	* @return array
242	*/
243	function acf_enable_filters( $filters = array() ) {
244
245	// Get state.
246	$prev_state = acf_get_filters();
247
248	// Allow specific filters to be enabled.
249	if ( $filters ) {
250	acf_set_filters( $filters );
251
252	// Set all modifiers as true.
253	} else {
254	acf_set_filters( array_map( '__return_true', $prev_state ) );
255	}
256
257	// Return prev state.
258	return $prev_state;
259	}
260
261	/**
262	* acf_idval
263	*
264	* Parses the provided value for an ID.
265	*
266	* @date 29/3/19
267	* @since ACF 5.7.14
268	*
269	* @param mixed $value A value to parse.
270	* @return integer
271	*/
272	function acf_idval( $value ) {
273
274	// Check if value is numeric.
275	if ( is_numeric( $value ) ) {
276	return (int) $value;
277
278	// Check if value is array.
279	} elseif ( is_array( $value ) ) {
280	return (int) isset( $value['ID'] ) ? $value['ID'] : 0;
281
282	// Check if value is object.
283	} elseif ( is_object( $value ) ) {
284	return (int) isset( $value->ID ) ? $value->ID : 0;
285	}
286
287	// Return default.
288	return 0;
289	}
290
291	/**
292	* acf_maybe_idval
293	*
294	* Checks value for potential id value.
295	*
296	* @date 6/4/19
297	* @since ACF 5.7.14
298	*
299	* @param mixed $value A value to parse.
300	* @return mixed
301	*/
302	function acf_maybe_idval( $value ) {
303	if ( $id = acf_idval( $value ) ) {
304	return $id;
305	}
306	return $value;
307	}
308
309	/**
310	* Convert any numeric strings into their equivalent numeric type. This function will
311	* work with both single values and arrays.
312	*
313	* @param mixed $value Either a single value or an array of values.
314	* @return mixed
315	*/
316	function acf_format_numerics( $value ) {
317	if ( is_array( $value ) ) {
318	return array_map(
319	function ( $v ) {
320	return is_numeric( $v ) ? $v + 0 : $v;
321	},
322	$value
323	);
324	}
325
326	return is_numeric( $value ) ? $value + 0 : $value;
327	}
328
329	/**
330	* acf_numval
331	*
332	* Casts the provided value as eiter an int or float using a simple hack.
333	*
334	* @date 11/4/19
335	* @since ACF 5.7.14
336	*
337	* @param mixed $value A value to parse.
338	* @return (int\|float)
339	*/
340	function acf_numval( $value ) {
341	return ( intval( $value ) == floatval( $value ) ) ? intval( $value ) : floatval( $value );
342	}
343
344	/**
345	* acf_idify
346	*
347	* Returns an id attribute friendly string.
348	*
349	* @date 24/12/17
350	* @since ACF 5.6.5
351	*
352	* @param string $str The string to convert.
353	* @return string
354	*/
355	function acf_idify( $str = '' ) {
356	return str_replace( array( '][', '[', ']' ), array( '-', '-', '' ), strtolower( $str ) );
357	}
358
359	/**
360	* Returns a slug friendly string.
361	*
362	* @date 24/12/17
363	* @since ACF 5.6.5
364	*
365	* @param string $str The string to convert.
366	* @param string $glue The glue between each slug piece.
367	* @return string
368	*/
369	function acf_slugify( $str = '', $glue = '-' ) {
370	$raw = $str;
371	$slug = str_replace( array( '_', '-', '/', ' ' ), $glue, strtolower( remove_accents( $raw ) ) );
372	$slug = preg_replace( '/[^A-Za-z0-9' . preg_quote( $glue ) . ']/', '', $slug );
373
374	/**
375	* Filters the slug created by acf_slugify().
376	*
377	* @since ACF 5.11.4
378	*
379	* @param string $slug The newly created slug.
380	* @param string $raw The original string.
381	* @param string $glue The separator used to join the string into a slug.
382	*/
383	return apply_filters( 'acf/slugify', $slug, $raw, $glue );
384	}
385
386	/**
387	* Returns a string with correct full stop punctuation.
388	*
389	* @date 12/7/19
390	* @since ACF 5.8.2
391	*
392	* @param string $str The string to format.
393	* @return string
394	*/
395	function acf_punctify( $str = '' ) {
396	if ( substr( trim( strip_tags( $str ) ), -1 ) !== '.' ) {
397	return trim( $str ) . '.';
398	}
399	return trim( $str );
400	}
401
402	/**
403	* acf_did
404	*
405	* Returns true if ACF already did an event.
406	*
407	* @date 30/8/19
408	* @since ACF 5.8.1
409	*
410	* @param string $name The name of the event.
411	* @return boolean
412	*/
413	function acf_did( $name ) {
414
415	// Return true if already did the event (preventing event).
416	if ( acf_get_data( "acf_did_$name" ) ) {
417	return true;
418
419	// Otherwise, update store and return false (allowing event).
420	} else {
421	acf_set_data( "acf_did_$name", true );
422	return false;
423	}
424	}
425
426	/**
427	* Returns the length of a string that has been submitted via $_POST.
428	*
429	* Uses the following process:
430	* 1. Unslash the string because posted values will be slashed.
431	* 2. Decode special characters because wp_kses() will normalize entities.
432	* 3. Treat line-breaks as a single character instead of two.
433	* 4. Use mb_strlen() to accommodate special characters.
434	*
435	* @date 04/06/2020
436	* @since ACF 5.9.0
437	*
438	* @param string $str The string to review.
439	* @return integer
440	*/
441	function acf_strlen( $str ) {
442	return mb_strlen( str_replace( "\r\n", "\n", wp_specialchars_decode( wp_unslash( $str ) ) ) );
443	}
444
445	/**
446	* Returns a value with default fallback.
447	*
448	* @date 6/4/20
449	* @since ACF 5.9.0
450	*
451	* @param mixed $value The value.
452	* @param mixed $default_value The default value.
453	* @return mixed
454	*/
455	function acf_with_default( $value, $default_value ) {
456	return $value ? $value : $default_value;
457	}
458
459	/**
460	* Returns the current priority of a running action.
461	*
462	* @date 14/07/2020
463	* @since ACF 5.9.0
464	*
465	* @param string $action The action name.
466	* @return integer\|boolean
467	*/
468	function acf_doing_action( $action ) {
469	global $wp_filter;
470	if ( isset( $wp_filter[ $action ] ) ) {
471	return $wp_filter[ $action ]->current_priority();
472	}
473	return false;
474	}
475
476	/**
477	* Returns the current URL.
478	*
479	* @date 23/01/2015
480	* @since ACF 5.1.5
481	*
482	* @return string
483	*/
484	function acf_get_current_url() {
485	// Ensure props exist to avoid PHP Notice during CLI commands.
486	if ( isset( $_SERVER['HTTP_HOST'], $_SERVER['REQUEST_URI'] ) ) {
487	return ( is_ssl() ? 'https' : 'http' ) . '://' . filter_var( $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], FILTER_SANITIZE_URL );
488	}
489	return '';
490	}
491
492	/**
493	* Sanitizes request arguments.
494	*
495	* @param mixed $args The data to sanitize.
496	*
497	* @return array\|boolean\|float\|integer\|mixed\|string
498	*/
499	function acf_sanitize_request_args( $args = array() ) {
500	switch ( gettype( $args ) ) {
501	case 'boolean':
502	return (bool) $args;
503	case 'integer':
504	return (int) $args;
505	case 'double':
506	return (float) $args;
507	case 'array':
508	$sanitized = array();
509	foreach ( $args as $key => $value ) {
510	$key = sanitize_text_field( $key );
511	$sanitized[ $key ] = acf_sanitize_request_args( $value );
512	}
513	return $sanitized;
514	case 'object':
515	return wp_kses_post_deep( $args );
516	case 'string':
517	default:
518	return wp_kses( $args, 'acf' );
519	}
520	}
521
522	/**
523	* Sanitizes file upload arrays.
524	*
525	* @since ACF 6.0.4
526	*
527	* @param array $args The file array.
528	*
529	* @return array
530	*/
531	function acf_sanitize_files_array( array $args = array() ) {
532	$defaults = array(
533	'name' => '',
534	'tmp_name' => '',
535	'type' => '',
536	'size' => 0,
537	'error' => '',
538	);
539
540	$args = wp_parse_args( $args, $defaults );
541
542	if ( empty( $args['name'] ) ) {
543	return $defaults;
544	}
545
546	if ( is_array( $args['name'] ) ) {
547	$files = array();
548	$files['name'] = acf_sanitize_files_value_array( $args['name'], 'sanitize_file_name' );
549	$files['tmp_name'] = acf_sanitize_files_value_array( $args['tmp_name'], 'sanitize_text_field' );
550	$files['type'] = acf_sanitize_files_value_array( $args['type'], 'sanitize_text_field' );
551	$files['size'] = acf_sanitize_files_value_array( $args['size'], 'absint' );
552	$files['error'] = acf_sanitize_files_value_array( $args['error'], 'absint' );
553	return $files;
554	}
555
556	$file = array();
557	$file['name'] = sanitize_file_name( $args['name'] );
558	$file['tmp_name'] = sanitize_text_field( $args['tmp_name'] );
559	$file['type'] = sanitize_text_field( $args['type'] );
560	$file['size'] = absint( $args['size'] );
561	$file['error'] = absint( $args['error'] );
562
563	return $file;
564	}
565
566	/**
567	* Sanitizes file upload values within the array.
568	*
569	* This addresses nested file fields within repeaters and groups.
570	*
571	* @since ACF 6.0.5
572	*
573	* @param array $array The file upload array.
574	* @param string $sanitize_function Callback used to sanitize array value.
575	* @return array
576	*/
577	function acf_sanitize_files_value_array( $array, $sanitize_function ) {
578	if ( ! function_exists( $sanitize_function ) ) {
579	return $array;
580	}
581
582	if ( ! is_array( $array ) ) {
583	return $sanitize_function( $array );
584	}
585
586	foreach ( $array as $key => $value ) {
587	if ( is_array( $value ) ) {
588	$array[ $key ] = acf_sanitize_files_value_array( $value, $sanitize_function );
589	} else {
590	$array[ $key ] = $sanitize_function( $value );
591	}
592	}
593
594	return $array;
595	}
596
597	/**
598	* Maybe unserialize, but don't allow any classes.
599	*
600	* @since ACF 6.1
601	*
602	* @param string $data String to be unserialized, if serialized.
603	* @return mixed The unserialized, or original data.
604	*/
605	function acf_maybe_unserialize( $data ) {
606	if ( is_serialized( $data ) ) { // Don't attempt to unserialize data that wasn't serialized going in.
607	return @unserialize( trim( $data ), array( 'allowed_classes' => false ) ); //phpcs:ignore -- allowed classes is false.
608	}
609
610	return $data;
611	}
612
613	/**
614	* Check if ACF is a beta-like release.
615	*
616	* @since ACF 6.3
617	*
618	* @return boolean True if the current install version contains a dash, indicating a alpha, beta or RC release.
619	*/
620	function acf_is_beta() {
621	return defined( 'ACF_VERSION' ) && strpos( ACF_VERSION, '-' ) !== false;
622	}
623
624	/**
625	* Returns the version of ACF when it was first activated.
626	* However, if ACF was first activated prior to the introduction of the acf_first_activated_version option,
627	* this function returns false (boolean) to indicate that the version could not be determined.
628	*
629	* @since ACF 6.3
630	*
631	* @return string\|boolean The (string) version of ACF when it was first activated, or false (boolean) if the version could not be determined.
632	*/
633	function acf_get_version_when_first_activated() {
634	// Check if ACF is network-activated on a multisite.
635	if ( is_multisite() ) {
636	$acf_dir_and_filename = basename( ACF_PATH ) . '/acf.php';
637	$plugins = get_site_option( 'active_sitewide_plugins' );
638
639	if ( isset( $plugins[ $acf_dir_and_filename ] ) ) {
640	$main_site_id = get_main_site_id();
641
642	if ( empty( $main_site_id ) ) {
643	return false;
644	}
645
646	// ACF is network activated, so get the version from main site's options.
647	return get_blog_option( $main_site_id, 'acf_first_activated_version', false );
648	}
649	}
650
651	// Check if ACF is activated on this single site.
652	return get_option( 'acf_first_activated_version', false );
653	}
654