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

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

advanced-custom-fields / includes Last commit date

admin 2 years ago ajax 3 years ago api 2 years ago fields 2 years ago forms 2 years ago legacy 4 years ago locations 3 years ago post-types 2 years ago rest-api 3 years ago walkers 2 years ago acf-bidirectional-functions.php 2 years ago acf-field-functions.php 3 years ago acf-field-group-functions.php 3 years ago acf-form-functions.php 3 years ago acf-helper-functions.php 2 years ago acf-hook-functions.php 4 years ago acf-input-functions.php 3 years ago acf-internal-post-type-functions.php 2 years ago acf-meta-functions.php 3 years ago acf-post-functions.php 4 years ago acf-post-type-functions.php 2 years ago acf-taxonomy-functions.php 3 years ago acf-user-functions.php 4 years ago acf-utility-functions.php 3 years ago acf-value-functions.php 2 years ago acf-wp-functions.php 2 years ago assets.php 2 years ago class-acf-data.php 3 years ago class-acf-internal-post-type.php 2 years ago compatibility.php 4 years ago deprecated.php 4 years ago fields.php 2 years ago l10n.php 3 years ago local-fields.php 2 years ago local-json.php 2 years ago local-meta.php 4 years ago locations.php 3 years ago loop.php 3 years ago media.php 3 years ago rest-api.php 4 years ago revisions.php 3 years ago third-party.php 3 years ago upgrades.php 3 years ago validation.php 2 years ago wpml.php 3 years ago

acf-helper-functions.php

682 lines

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