acf-helper-functions.php — Advanced Custom Fields (ACF®) 6.8.7

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

advanced-custom-fields / includes Last commit date

acf-helper-functions.php

721 lines

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