acf-field-group-functions.php — Advanced Custom Fields (ACF®) 6.8.9

advanced-custom-fields / includes / acf-field-group-functions.php

advanced-custom-fields / includes Last commit date

acf-field-group-functions.php

580 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	* acf_get_field_group
14	*
15	* Retrieves a field group for the given identifier.
16	*
17	* @date 30/09/13
18	* @since 5.0.0
19	*
20	* @param (int\|string) $id The field group ID, key or name.
21	* @return (array\|false) The field group array.
22	*/
23	function acf_get_field_group( $id = 0 ) {
24	return acf_get_internal_post_type( $id, 'acf-field-group' );
25	}
26
27	/**
28	* acf_get_raw_field_group
29	*
30	* Retrieves raw field group data for the given identifier.
31	*
32	* @date 18/1/19
33	* @since 5.7.10
34	*
35	* @param (int\|string) $id The field ID, key or name.
36	* @return (array\|false) The field group array.
37	*/
38	function acf_get_raw_field_group( $id = 0 ) {
39	return acf_get_raw_internal_post_type( $id, 'acf-field-group' );
40	}
41
42	/**
43	* acf_get_field_group_post
44	*
45	* Retrieves the field group's WP_Post object.
46	*
47	* @date 18/1/19
48	* @since 5.7.10
49	*
50	* @param (int\|string) $id The field group's ID, key or name.
51	* @return (array\|false) The field group's array.
52	*/
53	function acf_get_field_group_post( $id = 0 ) {
54	return acf_get_internal_post_type_post( $id, 'acf-field-group' );
55	}
56
57	/**
58	* acf_is_field_group_key
59	*
60	* Returns true if the given identifier is a field group key.
61	*
62	* @date 6/12/2013
63	* @since 5.0.0
64	*
65	* @param string $id The identifier.
66	* @return boolean
67	*/
68	function acf_is_field_group_key( $id = '' ) {
69	return acf_is_internal_post_type_key( $id, 'acf-field-group' );
70	}
71
72	/**
73	* Ensures the given field group is valid.
74	*
75	* @date 18/1/19
76	* @since 5.7.10
77	*
78	* @param array $field_group The field group array.
79	* @return array
80	*/
81	function acf_validate_field_group( $field_group = array() ) {
82	return acf_validate_internal_post_type( $field_group, 'acf-field-group' );
83	}
84
85	/**
86	* acf_get_valid_field_group
87	*
88	* Ensures the given field group is valid.
89	*
90	* @date 28/09/13
91	* @since 5.0.0
92	*
93	* @param array $field_group The field group array.
94	* @return array
95	*/
96	function acf_get_valid_field_group( $field_group = false ) {
97	return acf_validate_field_group( $field_group );
98	}
99
100	/**
101	* acf_translate_field_group
102	*
103	* Translates a field group's settings.
104	*
105	* @date 8/03/2016
106	* @since 5.3.2
107	*
108	* @param array $field_group The field group array.
109	* @return array
110	*/
111	function acf_translate_field_group( $field_group = array() ) {
112	return acf_translate_internal_post_type( $field_group, 'acf-field-group' );
113	}
114
115	/**
116	* acf_get_field_groups
117	*
118	* Returns and array of field_groups for the given $filter.
119	*
120	* @date 30/09/13
121	* @since 5.0.0
122	*
123	* @param array $filter An array of args to filter results by.
124	* @return array
125	*/
126	function acf_get_field_groups( $filter = array() ) {
127	return acf_get_internal_post_type_posts( 'acf-field-group', $filter );
128	}
129
130	/**
131	* acf_get_raw_field_groups
132	*
133	* Returns and array of raw field_group data.
134	*
135	* @date 18/1/19
136	* @since 5.7.10
137	*
138	* @param void
139	* @return array
140	*/
141	function acf_get_raw_field_groups() {
142	return acf_get_raw_internal_post_type_posts( 'acf-field-group' );
143	}
144
145	/**
146	* acf_filter_field_groups
147	*
148	* Returns a filtered aray of field groups based on the given $args.
149	*
150	* @date 29/11/2013
151	* @since 5.0.0
152	*
153	* @param array $field_groups An array of field groups.
154	* @param array $args An array of location args.
155	* @return array
156	*/
157	function acf_filter_field_groups( $field_groups, $args = array() ) {
158	return acf_filter_internal_post_type_posts( $field_groups, $args, 'acf-field-group' );
159	}
160
161	/**
162	* acf_get_field_group_visibility
163	*
164	* Returns true if the given field group's location rules match the given $args.
165	*
166	* @date 7/10/13
167	* @since 5.0.0
168	*
169	* @param array $field_groups An array of field groups.
170	* @param array $args An array of location args.
171	* @return boolean
172	*/
173	function acf_get_field_group_visibility( $field_group, $args = array() ) {
174
175	// Check if active.
176	if ( ! $field_group['active'] ) {
177	return false;
178	}
179
180	// Check if location rules exist
181	if ( $field_group['location'] ) {
182
183	// Get the current screen.
184	$screen = acf_get_location_screen( $args );
185
186	// Loop through location groups.
187	foreach ( $field_group['location'] as $group ) {
188
189	// ignore group if no rules.
190	if ( empty( $group ) ) {
191	continue;
192	}
193
194	// Loop over rules and determine if all rules match.
195	$match_group = true;
196	foreach ( $group as $rule ) {
197	if ( ! acf_match_location_rule( $rule, $screen, $field_group ) ) {
198	$match_group = false;
199	break;
200	}
201	}
202
203	// If this group matches, show the field group.
204	if ( $match_group ) {
205	return true;
206	}
207	}
208	}
209
210	// Return default.
211	return false;
212	}
213
214	/**
215	* acf_update_field_group
216	*
217	* Updates a field group in the database.
218	*
219	* @date 21/1/19
220	* @since 5.7.10
221	*
222	* @param array $field_group The field group array.
223	* @return array
224	*/
225	function acf_update_field_group( $field_group ) {
226	return acf_update_internal_post_type( $field_group, 'acf-field-group' );
227	}
228
229	/**
230	* _acf_apply_unique_field_group_slug
231	*
232	* Allows full control over 'acf-field-group' slugs.
233	*
234	* @date 21/1/19
235	* @since 5.7.10
236	*
237	* @param string $slug The post slug.
238	* @param integer $post_ID Post ID.
239	* @param string $post_status The post status.
240	* @param string $post_type Post type.
241	* @param integer $post_parent Post parent ID
242	* @param string $original_slug The original post slug.
243	*/
244	function _acf_apply_unique_field_group_slug( $slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug ) {
245
246	// Check post type and reset to original value.
247	if ( $post_type === 'acf-field-group' ) {
248	return $original_slug;
249	}
250
251	// Return slug.
252	return $slug;
253	}
254
255	/**
256	* acf_flush_field_group_cache
257	*
258	* Deletes all caches for this field group.
259	*
260	* @date 22/1/19
261	* @since 5.7.10
262	*
263	* @param array $field_group The field group array.
264	* @return void
265	*/
266	function acf_flush_field_group_cache( $field_group ) {
267	acf_flush_internal_post_type_cache( $field_group, 'acf-field-group' );
268	}
269
270	/**
271	* acf_delete_field_group
272	*
273	* Deletes a field group from the database.
274	*
275	* @date 21/1/19
276	* @since 5.7.10
277	*
278	* @param (int\|string) $id The field group ID, key or name.
279	* @return boolean True if field group was deleted.
280	*/
281	function acf_delete_field_group( $id = 0 ) {
282	return acf_delete_internal_post_type( $id, 'acf-field-group' );
283	}
284
285	/**
286	* acf_trash_field_group
287	*
288	* Trashes a field group from the database.
289	*
290	* @date 2/10/13
291	* @since 5.0.0
292	*
293	* @param (int\|string) $id The field group ID, key or name.
294	* @return boolean True if field group was trashed.
295	*/
296	function acf_trash_field_group( $id = 0 ) {
297	return acf_trash_internal_post_type( $id, 'acf-field-group' );
298	}
299
300	/**
301	* acf_untrash_field_group
302	*
303	* Restores a field_group from the trash.
304	*
305	* @date 2/10/13
306	* @since 5.0.0
307	*
308	* @param (int\|string) $id The field_group ID, key or name.
309	* @return boolean True if field_group was trashed.
310	*/
311	function acf_untrash_field_group( $id = 0 ) {
312	return acf_untrash_internal_post_type( $id, 'acf-field-group' );
313	}
314
315	/**
316	* Filter callback which returns the previous post_status instead of "draft" for the "acf-field-group" post type.
317	*
318	* Prior to WordPress 5.6.0, this filter was not needed as restored posts were always assigned their original status.
319	*
320	* @since 5.9.5
321	*
322	* @param string $new_status The new status of the post being restored.
323	* @param integer $post_id The ID of the post being restored.
324	* @param string $previous_status The status of the post at the point where it was trashed.
325	* @return string.
326	*/
327	function _acf_untrash_field_group_post_status( $new_status, $post_id, $previous_status ) {
328	return ( get_post_type( $post_id ) === 'acf-field-group' ) ? $previous_status : $new_status;
329	}
330
331	/**
332	* acf_is_field_group
333	*
334	* Returns true if the given params match a field group.
335	*
336	* @date 21/1/19
337	* @since 5.7.10
338	*
339	* @param array $field_group The field group array.
340	* @param mixed $id An optional identifier to search for.
341	* @return boolean
342	*/
343	function acf_is_field_group( $field_group = false ) {
344	return acf_is_internal_post_type( $field_group, 'acf-field-group' );
345	}
346
347	/**
348	* acf_duplicate_field_group
349	*
350	* Duplicates a field group.
351	*
352	* @date 16/06/2014
353	* @since 5.0.0
354	*
355	* @param (int\|string) $id The field_group ID, key or name.
356	* @param integer $new_post_id Optional post ID to override.
357	* @return array The new field group.
358	*/
359	function acf_duplicate_field_group( $id = 0, $new_post_id = 0 ) {
360	return acf_duplicate_internal_post_type( $id, $new_post_id, 'acf-field-group' );
361	}
362
363	/**
364	* Activates or deactivates a field group.
365	*
366	* @param integer\|string $id The field_group ID, key or name.
367	* @param boolean $activate True if the post should be activated.
368	* @return boolean
369	*/
370	function acf_update_field_group_active_status( $id, $activate = true ) {
371	return acf_update_internal_post_type_active_status( $id, $activate, 'acf-field-group' );
372	}
373
374	/**
375	* acf_get_field_group_style
376	*
377	* Returns the CSS styles generated from field group settings.
378	*
379	* @date 20/10/13
380	* @since 5.0.0
381	*
382	* @param array $field_group The field group array.
383	* @return string.
384	*/
385	function acf_get_field_group_style( $field_group ) {
386
387	// Vars.
388	$style = '';
389	$elements = array(
390	'permalink' => '#edit-slug-box',
391	'the_content' => '#postdivrich',
392	'excerpt' => '#postexcerpt',
393	'custom_fields' => '#postcustom',
394	'discussion' => '#commentstatusdiv',
395	'comments' => '#commentsdiv',
396	'slug' => '#slugdiv',
397	'author' => '#authordiv',
398	'format' => '#formatdiv',
399	'page_attributes' => '#pageparentdiv',
400	'featured_image' => '#postimagediv',
401	'revisions' => '#revisionsdiv',
402	'categories' => '#categorydiv',
403	'tags' => '#tagsdiv-post_tag',
404	'send-trackbacks' => '#trackbacksdiv',
405	);
406
407	// Loop over field group settings and generate list of selectors to hide.
408	if ( is_array( $field_group['hide_on_screen'] ) ) {
409	$hide = array();
410	foreach ( $field_group['hide_on_screen'] as $k ) {
411	if ( isset( $elements[ $k ] ) ) {
412	$id = $elements[ $k ];
413	$hide[] = $id;
414	$hide[] = '#screen-meta label[for=' . substr( $id, 1 ) . '-hide]';
415	}
416	}
417	$style = implode( ', ', $hide ) . ' {display: none;}';
418	}
419
420	/**
421	* Filters the generated CSS styles.
422	*
423	* @date 12/02/2014
424	* @since 5.0.0
425	*
426	* @param string $style The CSS styles.
427	* @param array $field_group The field group array.
428	*/
429	return apply_filters( 'acf/get_field_group_style', $style, $field_group );
430	}
431
432	/**
433	* acf_get_field_group_edit_link
434	*
435	* Checks if the current user can edit the field group and returns the edit url.
436	*
437	* @date 23/9/18
438	* @since 5.7.7
439	*
440	* @param integer $post_id The field group ID.
441	* @return string
442	*/
443	function acf_get_field_group_edit_link( $post_id ) {
444	return acf_get_internal_post_type_edit_link( $post_id, 'acf-field-group' );
445	}
446
447	/**
448	* acf_prepare_field_group_for_export
449	*
450	* Returns a modified field group ready for export.
451	*
452	* @date 11/03/2014
453	* @since 5.0.0
454	*
455	* @param array $field_group The field group array.
456	* @return array
457	*/
458	function acf_prepare_field_group_for_export( $field_group = array() ) {
459	return acf_prepare_internal_post_type_for_export( $field_group, 'acf-field-group' );
460	}
461
462	/**
463	* acf_prepare_field_group_for_import
464	*
465	* Prepares a field group for the import process.
466	*
467	* @date 21/11/19
468	* @since 5.8.8
469	*
470	* @param array $field_group The field group array.
471	* @return array
472	*/
473	function acf_prepare_field_group_for_import( $field_group ) {
474	return acf_prepare_internal_post_type_for_import( $field_group, 'acf-field-group' );
475	}
476
477	/**
478	* acf_import_field_group
479	*
480	* Imports a field group into the databse.
481	*
482	* @date 11/03/2014
483	* @since 5.0.0
484	*
485	* @param array $field_group The field group array.
486	* @return array The new field group.
487	*/
488	function acf_import_field_group( $field_group ) {
489	return acf_import_internal_post_type( $field_group, 'acf-field-group' );
490	}
491
492	/**
493	* Returns an array of tabs for the field group settings.
494	* We combine a list of default tabs with filtered tabs.
495	* I.E. Default tabs should be static and should not be changed by the
496	* filtered tabs.
497	*
498	* @since 6.1
499	*
500	* @return array Key/value array of the default settings tabs for field group settings.
501	*/
502	function acf_get_combined_field_group_settings_tabs() {
503	$default_field_group_settings_tabs = array(
504	'location_rules' => __( 'Location Rules', 'acf' ),
505	'presentation' => __( 'Presentation', 'acf' ),
506	'group_settings' => __( 'Group Settings', 'acf' ),
507	);
508
509	$field_group_settings_tabs = (array) apply_filters( 'acf/field_group/additional_group_settings_tabs', array() );
510
511	// remove any default tab values from the filter tabs.
512	foreach ( $field_group_settings_tabs as $key => $tab ) {
513	if ( isset( $default_field_group_settings_tabs[ $key ] ) ) {
514	unset( $field_group_settings_tabs[ $key ] );
515	}
516	}
517
518	$combined_field_group_settings_tabs = array_merge( $default_field_group_settings_tabs, $field_group_settings_tabs );
519
520	return $combined_field_group_settings_tabs;
521	}
522
523	/**
524	* Checks if a field group has the provided location rule.
525	*
526	* @since 6.2.8
527	*
528	* @param integer $post_id The post ID of the field group.
529	* @param string $location The location type to check for.
530	* @return boolean
531	*/
532	function acf_field_group_has_location_type( int $post_id, string $location ) {
533	if ( empty( $post_id ) \|\| empty( $location ) ) {
534	return false;
535	}
536
537	$field_group = acf_get_field_group( (int) $post_id );
538
539	if ( empty( $field_group['location'] ) ) {
540	return false;
541	}
542
543	foreach ( $field_group['location'] as $rule_group ) {
544	$params = array_column( $rule_group, 'param' );
545
546	if ( in_array( $location, $params, true ) ) {
547	return true;
548	}
549	}
550
551	return false;
552	}
553
554	/**
555	* Retrieves the field group title, or display title if set.
556	*
557	* @since 6.6
558	*
559	* @param array\|integer $field_group The field group array or ID.
560	* @return string The field group title.
561	*/
562	function acf_get_field_group_title( $field_group ): string {
563	if ( is_numeric( $field_group ) ) {
564	$field_group = acf_get_field_group( $field_group );
565	}
566
567	$title = '';
568	if ( ! empty( $field_group['title'] ) && is_string( $field_group['title'] ) ) {
569	$title = $field_group['title'];
570	}
571
572	// Override with the Display Title if set.
573	if ( ! empty( $field_group['display_title'] ) && is_string( $field_group['display_title'] ) ) {
574	$title = $field_group['display_title'];
575	}
576
577	// Filter and return.
578	return apply_filters( 'acf/get_field_group_title', esc_html( $title ), $field_group );
579	}
580